Writing for developers workshop

Transcript

1. 1.

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

   developers
2. 2.

   @alicebartlett Disclaimer: I AM NOT A WRITER

3. 3.

   1. Why writing is important for developers 2. Tips for

   writing well 3. A exercise!
4. 4.

   1. Why writing is important for developers @alicebartlett

5. 5.

   @alicebartlett This should be obvious: part of being an effective

   developer is being able to communicate ideas and instructions well
6. 6.

   @alicebartlett A useful tool for communicating is writing!

7. 7.

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

   payoff is huge
8. 8.

   @alicebartlett Writing clear and concise documentation is going to be

   strategically important this year.
9. 9.

   @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
10. 10.

    @alicebartlett If these codebases are well documented the it’s a

    lot easier to work on them
11. 11.

    @alicebartlett Writing well doesn’t need to be onerous. It requires

    a bit of effort, but luckily there are a lot of tools around.
12. 12.

    @alicebartlett Good writing is clear and concise.

13. 13.

    Clear writing is unambiguous. The reader understands precisely what the

    writer intended. @alicebartlett
14. 14.

    Concise writing is short. The writer communicated her idea in

    as few words as possible thereby not wasting the reader’s time. @alicebartlett
15. 15.

    1. Why writing is important for developers 2. Some tips

    for writing well 3. A exercise!
16. 16.

    2. Some tips for writing well @alicebartlett

17. 17.

    @alicebartlett

18. 18.

    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
19. 19.

    @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
20. 20.

    @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
21. 21.

    @alicebartlett And, yes, there are cases where an apostrophe can

    change the meaning of a sentence.
22. 22.

    Structure things for skim readers @alicebartlett Use headings, tables, lists,

    asides, bold, emphasis…
23. 23.

    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
24. 24.

    Headings should give you the gist @alicebartlett They should summarise

    in a single sentence what follows
25. 25.

    @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
26. 26.

    @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
27. 27.

    @alicebartlett Be conversational It’s OK to use contractions like “there’s”

    instead of “there is”. Our documentation can be useful without being formal.
28. 28.

    @alicebartlett Be conversational Unless you’re writing a formal document such

    as a technical specification as defined by the W3C.
29. 29.

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

    “will”
30. 30.

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

    June”
31. 31.

    @alicebartlett Not “Aiming for completion end of June”

32. 32.

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

    of June”
33. 33.

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

    equivocate
34. 34.

    @alicebartlett These words are bad for the reader, who is

    looking for clear instructions.
35. 35.

    @alicebartlett Avoiding them forces you to think about what you

    actually mean.
36. 36.

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

37. 37.

    @alicebartlett “The best strategy is X” But

38. 38.

    In the active voice, the subject of the sentence does

    the action @alicebartlett Avoid the passive voice
39. 39.

    @alicebartlett The active voice forces you to take responsibility for

    what you are saying
40. 40.

    @alicebartlett We use the passive voice when we’re trying to

    distance ourselves from the message
41. 41.

    @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
42. 42.

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

43. 43.

    @alicebartlett Monzo’s style guide contains a useful hack for telling

    if you’ve used the passive voice
44. 44.

    @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
45. 45.

    @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
46. 46.

    @alicebartlett Avoid metaphors and idioms

47. 47.

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

48. 48.

    @alicebartlett This phrase exists in other languages

49. 49.

    @alicebartlett In Italian, the equivalent phrase is

50. 50.

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

51. 51.

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

    a full wine barrel and a drunk wife”
52. 52.

    Avoid “simply”, “just” @alicebartlett

53. 53.

    Simply rotate the key @alicebartlett

54. 54.

    “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
55. 55.

    Simply rotate the key @alicebartlett

56. 56.

    @alicebartlett Avoid jargon and acronyms

57. 57.

    @alicebartlett Jargon and acronyms create an in- group who know

    what they mean, and an out-group who do not
58. 58.

    @alicebartlett Jargon is lazy

59. 59.

    Hemingway (named after Earnest Hemingway) is an app that shows

    when your writing isn’t clear @alicebartlett Use Hemingway
60. 60.

    @alicebartlett

61. 61.

    None
62. 62.

    1. Why writing is important for developers 2. Some tips

    for writing well 3. A exercise!