Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Sign up for free
Menu
Search
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Pricing
Search
Sign in
Sign up for free
Writing for developers workshop
Search
Sponsored
·
SiteGround - Reliable hosting with speed, security, and support you can count on.
→
Alice Bartlett
January 24, 2019
Technology
310
1
Share
Embed
Copy iframe code
Copy JS code
Copy link
Start on current slide
Writing for developers workshop
Alice Bartlett
January 24, 2019
Transcript
62 slides
Alice Bartlett Principal Engineer, Customer Products team @alicebartlett Writing for
developers
@alicebartlett Disclaimer: I AM NOT A WRITER
1. Why writing is important for developers 2. Tips for
writing well 3. A exercise!
1. Why writing is important for developers @alicebartlett
@alicebartlett This should be obvious: part of being an effective
developer is being able to communicate ideas and instructions well
@alicebartlett A useful tool for communicating is writing!
@alicebartlett Writing clearly and concisely can be difficult, but the
payoff is huge
@alicebartlett Writing clear and concise documentation is going to be
strategically important this year.
@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
@alicebartlett If these codebases are well documented the it’s a
lot easier to work on them
@alicebartlett Writing well doesn’t need to be onerous. It requires
a bit of effort, but luckily there are a lot of tools around.
@alicebartlett Good writing is clear and concise.
Clear writing is unambiguous. The reader understands precisely what the
writer intended. @alicebartlett
Concise writing is short. The writer communicated her idea in
as few words as possible thereby not wasting the reader’s time. @alicebartlett
1. Why writing is important for developers 2. Some tips
for writing well 3. A exercise!
2. Some tips for writing well @alicebartlett
@alicebartlett
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
@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
@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
@alicebartlett And, yes, there are cases where an apostrophe can
change the meaning of a sentence.
Structure things for skim readers @alicebartlett Use headings, tables, lists,
asides, bold, emphasis…
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
Headings should give you the gist @alicebartlett They should summarise
in a single sentence what follows
@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
@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
@alicebartlett Be conversational It’s OK to use contractions like “there’s”
instead of “there is”. Our documentation can be useful without being formal.
@alicebartlett Be conversational Unless you’re writing a formal document such
as a technical specification as defined by the W3C.
@alicebartlett Be concrete and personal Use “you” and “we” Use
“will”
@alicebartlett Not “The aim is to complete phase one by
June”
@alicebartlett Not “Aiming for completion end of June”
@alicebartlett But “We will complete phase one by the end
of June”
Avoid words like “probably”, “maybe”, “might”, “could be” @alicebartlett Don’t
equivocate
@alicebartlett These words are bad for the reader, who is
looking for clear instructions.
@alicebartlett Avoiding them forces you to think about what you
actually mean.
@alicebartlett “We think the best strategy is X” Not
@alicebartlett “The best strategy is X” But
In the active voice, the subject of the sentence does
the action @alicebartlett Avoid the passive voice
@alicebartlett The active voice forces you to take responsibility for
what you are saying
@alicebartlett We use the passive voice when we’re trying to
distance ourselves from the message
@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
https://www.mcsweeneys.net/articles/an-interactive-guide-to-ambiguous-grammar
@alicebartlett Monzo’s style guide contains a useful hack for telling
if you’ve used the passive voice
@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 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
@alicebartlett Avoid metaphors and idioms
@alicebartlett “You can’t have your cake and eat it too”
@alicebartlett This phrase exists in other languages
@alicebartlett In Italian, the equivalent phrase is
@alicebartlett “Volere la botte piena e la moglie ubriaca”
@alicebartlett “Volere la botte piena e la moglie ubriaca” “Want
a full wine barrel and a drunk wife”
Avoid “simply”, “just” @alicebartlett
Simply rotate the key @alicebartlett
“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
Simply rotate the key @alicebartlett
@alicebartlett Avoid jargon and acronyms
@alicebartlett Jargon and acronyms create an in- group who know
what they mean, and an out-group who do not
@alicebartlett Jargon is lazy
Hemingway (named after Earnest Hemingway) is an app that shows
when your writing isn’t clear @alicebartlett Use Hemingway
@alicebartlett
None
1. Why writing is important for developers 2. Some tips
for writing well 3. A exercise!
More Decks by Alice Bartlett
See All by Alice Bartlett
Strategy workshop from LDX3 Director+
alicebartlett
0
900
The Journey of a Byline
alicebartlett
0
440
Getting more from Git
alicebartlett
0
1.3k
presentations_ft.pdf
alicebartlett
1
450
All Day Hey! - Can't you make it more like bootstrap?
alicebartlett
2
2.4k
Case study on the FT's Responsive Image Service
alicebartlett
0
650
Git for Humans
alicebartlett
67
37k
FT Accessibility 101
alicebartlett
2
790
Can't you make it more like Bootstrap? (CASCADIA CONF)
alicebartlett
1
1.3k
Other Decks in Technology
See All in Technology
認知負荷の減らし方 ~開発にも日常業務にも活かせるノウハウ~
minorun365
PRO
17
10k
AWS Blocksで AIエージェント作れるの知ってます?
kmiya84377
1
170
目を覚ませ!僕らの認証情報が何者かに侵略されてるぞ
tkito
2
490
人の努力に頼らないセキュリティをエンジニアリングする在り方 / An approach to engineering security that does not rely on human effort
carta_engineering
0
240
Terraform 0 to 100:100個以上のリポジトリを常に最新にし続けるための自動化
sue445
3
1.4k
業務の傍らで進める改善ループエンジニアリング
bengo4com
1
240
Re:ゼロから始めるシェアハウスのペットな鯖
silmin_
0
270
Amazon EFS のマルウェアスキャンをClamAV で自前実装したら苦労した話
mtmtfactory01
0
110
統制されたID・権限をどう利用するか : DPoP/FAPIによるAPIセキュリティ強化
oidfj
2
300
Dark Web - Como o Cibercrime Opera na Internet
nicholsjasper
0
110
メディアアートを〈拡張〉する——器官学と個体化論を手がかりに
_kotobuki_
0
130
Platform Engineering をベースとした Agentic Software Factory の実践
110y
3
980
Featured
See All Featured
We Have a Design System, Now What?
morganepeng
55
8.4k
Practical Tips for Bootstrapping Information Extraction Pipelines
honnibal
25
2.2k
No one is an island. Learnings from fostering a developers community.
thoeni
21
3.9k
Testing 201, or: Great Expectations
jmmastey
46
8.4k
Keith and Marios Guide to Fast Websites
keithpitt
413
23k
How to train your dragon (web standard)
notwaldorf
96
6.9k
Intergalactic Javascript Robots from Outer Space
tanoku
273
28k
Designing Experiences People Love
moore
143
24k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
230
23k
Paper Plane
katiecoart
PRO
6
55k
Public Speaking Without Barfing On Your Shoes - THAT 2023
reverentgeek
1
670
Groundhog Day: Seeking Process in Gaming for Health
codingconduct
0
500