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
@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!