Slide 1

Slide 1 text

Alice Bartlett Principal Engineer, Customer Products team @alicebartlett Writing for developers

Slide 2

Slide 2 text

@alicebartlett Disclaimer: I AM NOT A WRITER

Slide 3

Slide 3 text

1. Why writing is important for developers 2. Tips for writing well 3. A exercise!

Slide 4

Slide 4 text

1. Why writing is important for developers @alicebartlett

Slide 5

Slide 5 text

@alicebartlett This should be obvious: part of being an effective developer is being able to communicate ideas and instructions well

Slide 6

Slide 6 text

@alicebartlett A useful tool for communicating is writing!

Slide 7

Slide 7 text

@alicebartlett Writing clearly and concisely can be difficult, but the payoff is huge

Slide 8

Slide 8 text

@alicebartlett Writing clear and concise documentation is going to be strategically important this year.

Slide 9

Slide 9 text

@alicebartlett This year we have more code than ever to maintain and so people are going to need to work on things they haven’t worked on before

Slide 10

Slide 10 text

@alicebartlett If these codebases are well documented the it’s a lot easier to work on them

Slide 11

Slide 11 text

@alicebartlett Writing well doesn’t need to be onerous. It requires a bit of effort, but luckily there are a lot of tools around.

Slide 12

Slide 12 text

@alicebartlett Good writing is clear and concise.

Slide 13

Slide 13 text

Clear writing is unambiguous. The reader understands precisely what the writer intended. @alicebartlett

Slide 14

Slide 14 text

Concise writing is short. The writer communicated her idea in as few words as possible thereby not wasting the reader’s time. @alicebartlett

Slide 15

Slide 15 text

1. Why writing is important for developers 2. Some tips for writing well 3. A exercise!

Slide 16

Slide 16 text

2. Some tips for writing well @alicebartlett

Slide 17

Slide 17 text

@alicebartlett

Slide 18

Slide 18 text

Grammatical correctness is important but it is not everything @alicebartlett Its, it’s, there, their, they’re. It’s easy to get hung up on apostrophe usage or spelling but there are more important things to focus on

Slide 19

Slide 19 text

@alicebartlett These minor errors can be a distraction from thinking further about the words you’ve chosen and how well they're communicating your thoughts and intent

Slide 20

Slide 20 text

@alicebartlett Ideally your words would be good and your grammar would be flawless. But grammar won’t save you if the communication of your idea is poor in other ways

Slide 21

Slide 21 text

@alicebartlett And, yes, there are cases where an apostrophe can change the meaning of a sentence.

Slide 22

Slide 22 text

Structure things for skim readers @alicebartlett Use headings, tables, lists, asides, bold, emphasis…

Slide 23

Slide 23 text

Don’t bury the lede @alicebartlett Put the most important information at the top of the section. Don’t make people read a whole paragraph to understand the most important part

Slide 24

Slide 24 text

Headings should give you the gist @alicebartlett They should summarise in a single sentence what follows

Slide 25

Slide 25 text

@alicebartlett How do I raise a ticket? // information on how to raise a ticket Raise a ticket in Jira // information on how to raise a ticket

Slide 26

Slide 26 text

@alicebartlett How do I raise a ticket? // information on how to raise a ticket Raise a ticket in Jira // information on how to raise a ticket // Better // OK

Slide 27

Slide 27 text

@alicebartlett Be conversational It’s OK to use contractions like “there’s” instead of “there is”. Our documentation can be useful without being formal.

Slide 28

Slide 28 text

@alicebartlett Be conversational Unless you’re writing a formal document such as a technical specification as defined by the W3C.

Slide 29

Slide 29 text

@alicebartlett Be concrete and personal Use “you” and “we” Use “will”

Slide 30

Slide 30 text

@alicebartlett Not “The aim is to complete phase one by June”

Slide 31

Slide 31 text

@alicebartlett Not “Aiming for completion end of June”

Slide 32

Slide 32 text

@alicebartlett But “We will complete phase one by the end of June”

Slide 33

Slide 33 text

Avoid words like “probably”, “maybe”, “might”, “could be” @alicebartlett Don’t equivocate

Slide 34

Slide 34 text

@alicebartlett These words are bad for the reader, who is looking for clear instructions.

Slide 35

Slide 35 text

@alicebartlett Avoiding them forces you to think about what you actually mean.

Slide 36

Slide 36 text

@alicebartlett “We think the best strategy is X” Not

Slide 37

Slide 37 text

@alicebartlett “The best strategy is X” But

Slide 38

Slide 38 text

In the active voice, the subject of the sentence does the action @alicebartlett Avoid the passive voice

Slide 39

Slide 39 text

@alicebartlett The active voice forces you to take responsibility for what you are saying

Slide 40

Slide 40 text

@alicebartlett We use the passive voice when we’re trying to distance ourselves from the message

Slide 41

Slide 41 text

@alicebartlett I’ve made a mistake We’ll email you We’ve decided A mistake was made You will be emailed A decision has been made

Slide 42

Slide 42 text

https://www.mcsweeneys.net/articles/an-interactive-guide-to-ambiguous-grammar

Slide 43

Slide 43 text

@alicebartlett Monzo’s style guide contains a useful hack for telling if you’ve used the passive voice

Slide 44

Slide 44 text

@alicebartlett I’ve made a mistake We’ll email you We’ve decided A mistake was made You will be emailed A decision has been made

Slide 45

Slide 45 text

@alicebartlett I’ve made a mistake by monkeys We’ll email you by monkeys We’ve decided by monkeys A mistake was made by monkeys You will be emailed by monkeys A decision has been made by monkeys

Slide 46

Slide 46 text

@alicebartlett Avoid metaphors and idioms

Slide 47

Slide 47 text

@alicebartlett “You can’t have your cake and eat it too”

Slide 48

Slide 48 text

@alicebartlett This phrase exists in other languages

Slide 49

Slide 49 text

@alicebartlett In Italian, the equivalent phrase is

Slide 50

Slide 50 text

@alicebartlett “Volere la botte piena e la moglie ubriaca”

Slide 51

Slide 51 text

@alicebartlett “Volere la botte piena e la moglie ubriaca” “Want a full wine barrel and a drunk wife”

Slide 52

Slide 52 text

Avoid “simply”, “just” @alicebartlett

Slide 53

Slide 53 text

Simply rotate the key @alicebartlett

Slide 54

Slide 54 text

“Simply” adds no value to this sentence. If you don’t know how to rotate the key, it makes you feel bad. If you do, then you don’t need to know it’s simple @alicebartlett

Slide 55

Slide 55 text

Simply rotate the key @alicebartlett

Slide 56

Slide 56 text

@alicebartlett Avoid jargon and acronyms

Slide 57

Slide 57 text

@alicebartlett Jargon and acronyms create an in- group who know what they mean, and an out-group who do not

Slide 58

Slide 58 text

@alicebartlett Jargon is lazy

Slide 59

Slide 59 text

Hemingway (named after Earnest Hemingway) is an app that shows when your writing isn’t clear @alicebartlett Use Hemingway

Slide 60

Slide 60 text

@alicebartlett

Slide 61

Slide 61 text

No content

Slide 62

Slide 62 text

1. Why writing is important for developers 2. Some tips for writing well 3. A exercise!