Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Writing for developers workshop

Writing for developers workshop

Alice Bartlett

January 24, 2019
Tweet

More Decks by Alice Bartlett

Other Decks in Technology

Transcript

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

    View Slide

  2. @alicebartlett
    Disclaimer: I AM NOT A WRITER

    View Slide

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

    View Slide

  4. 1. Why writing is important for
    developers
    @alicebartlett

    View Slide

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

    View Slide

  6. @alicebartlett
    A useful tool for communicating
    is writing!

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide

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

    View Slide

  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.

    View Slide

  12. @alicebartlett
    Good writing is clear and concise.

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  16. 2. Some tips for writing well
    @alicebartlett

    View Slide

  17. @alicebartlett

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide

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

    View Slide

  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

    View Slide

  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

    View Slide

  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.

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  31. @alicebartlett
    Not
    “Aiming for completion end of June”

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  37. @alicebartlett
    “The best strategy is X”
    But

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide

  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

    View Slide

  46. @alicebartlett
    Avoid metaphors and idioms

    View Slide

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

    View Slide

  48. @alicebartlett
    This phrase exists in other languages

    View Slide

  49. @alicebartlett
    In Italian, the equivalent phrase is

    View Slide

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

    View Slide

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

    View Slide

  52. Avoid “simply”, “just”
    @alicebartlett

    View Slide

  53. Simply rotate the key
    @alicebartlett

    View Slide

  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

    View Slide

  55. Simply rotate the key
    @alicebartlett

    View Slide

  56. @alicebartlett
    Avoid jargon and acronyms

    View Slide

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

    View Slide

  58. @alicebartlett
    Jargon is lazy

    View Slide

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

    View Slide

  60. @alicebartlett

    View Slide

  61. View Slide

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

    View Slide