Writing for developers workshop

Writing for developers workshop

Df057cdadda4cd7a2a2db52576de1bf2?s=128

Alice Bartlett

January 24, 2019
Tweet

Transcript

  1. 5.

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

    developer is being able to communicate ideas and instructions well
  2. 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
  3. 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.
  4. 14.

    Concise writing is short. The writer communicated her idea in

    as few words as possible thereby not wasting the reader’s time. @alicebartlett
  5. 15.
  6. 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
  7. 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
  8. 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
  9. 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
  10. 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
  11. 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
  12. 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.
  13. 28.

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

    as a technical specification as defined by the W3C.
  14. 34.
  15. 38.

    In the active voice, the subject of the sentence does

    the action @alicebartlett Avoid the passive voice
  16. 40.
  17. 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
  18. 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
  19. 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
  20. 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
  21. 57.

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

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

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

    when your writing isn’t clear @alicebartlett Use Hemingway
  23. 61.
  24. 62.