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

On Writing Friendly and Welcoming Documentation / NodeConf Budapest

Tracy Osborn
January 20, 2017
210

On Writing Friendly and Welcoming Documentation / NodeConf Budapest

Tracy Osborn

January 20, 2017
Tweet

Transcript

  1. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Writing So Your Words Are Read 
 How to write documentation and content that everyone would want to read and can understand.
  2. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Hi, I’m Tracy! @limedaring (daring, not darling)
  3. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  4. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  5. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  6. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring • Too long and wordy.
  7. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring • Too long and wordy. • Too technical and complex.
  8. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring • Too long and wordy. • Too technical and complex. • No pictures.
  9. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring • Too long and wordy. • Too technical and complex. • No pictures. • Outdated.
  10. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring • Too long and wordy. • Too technical and complex. • No pictures. • Outdated. • Incorrect directions.
  11. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring • Too long and wordy. • Too technical and complex. • No pictures. • Outdated. • Incorrect directions. • No documentation at all.
  12. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  13. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Better documentation and writing = More users. Less support requests. More contributors.
  14. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  15. NO DE CO NF ARGENTI NA T R AC Y

    O S B O R N @limedaring
  16. NO DE CO NF ARGENTI NA T R AC Y

    O S B O R N @limedaring
  17. FLU EN T CO NFER ENC E T RAC Y

    OS B OR N @limedaring
  18. FLU EN T CO NFER ENC E T RAC Y

    OS B OR N @limedaring
  19. FLU EN T CO NFER ENC E T RAC Y

    OS B OR N @limedaring
  20. FLU EN T CO NFER ENC E T RAC Y

    OS B OR N @limedaring
  21. FLU EN T CO NFER ENC E T RAC Y

    OS B OR N @limedaring
  22. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Most of these tips work 
 for all writing.
  23. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring How do we make our content, technical writing, and documentation easy to read and enjoyable?
  24. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Creating friendly and welcoming writing. 
 (Let’s throw some best practices out the window.)
  25. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Remember — 
 your readers aren’t you.
  26. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  27. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  28. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  29. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Write like a human, not a machine.
  30. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  31. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring But… avoid cultural references since they won’t translate.
  32. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  33. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Requests is the only Non-GMO HTTP library for Python, safe for human consumption.
  34. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Try personas — create a character and write for them.
  35. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring “What would Fred (a designer working on his first programming project) need to know?”
  36. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Remember that terms that are obvious might not be obvious to others.
  37. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  38. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring “Cream the butter”
  39. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring “Cream the butter” “Truss the bird”
  40. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites”
  41. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat”
  42. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat” “Shock the vegetables”
  43. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat” “Shock the vegetables”
  44. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Link anything that you 
 don’t want to explain.
  45. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  46. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring To get someone started with your project: teach — don’t tell. http://stevelosh.com/blog/2013/09/teach-dont-tell/
  47. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Reading the source works for someone already familiar with your project. Your writing about your project and documentation needs to get them to that point.
  48. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  49. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Dumb things down 
 (without making them dumb.)
  50. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  51. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  52. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  53. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  54. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Use gender-neutral language.
  55. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  56. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Try to avoid pronouns or rewrite your sentences to use plural pronouns. More: http://techwhirl.com/gender-neutral-technical-writing/
  57. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring The basics of 
 writing clearly. 
 (Shorter is better, yo.)
  58. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Cut down your content. 
 Two to three sentences per paragraph.
  59. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Break into bullets and use lots of headers. Make it easy to skim.
  60. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Use italics and bolding to 
 break up paragraphs.
  61. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring We made a bunch of changes: The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. Screenshots of the admin have been updated to reflect the new Django 1.9 styles. The few minor typos have been fixed. Updated the version of django- registration-redux that we use to 1.3. Last but not least, the Introduction has been updated. We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django-registration-redux that we use to 1.3. • Introduction has been updated.
  62. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django-registration-redux that we use to 1.3. • Introduction has been updated. We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django- registration-redux that we use to 1.3. • Introduction has been updated.
  63. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable.
 • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. 
 • The few minor typos have been fixed. • Updated the version of django- registration-redux that we use to 1.3. 
 • Introduction has been updated. We made a bunch of changes: The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. Screenshots of the admin have been updated to reflect the new Django 1.9 styles. The few minor typos have been fixed. Updated the version of django- registration-redux that we use to 1.3. Last but not least, the Introduction has been updated.
  64. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Don’t forget your headlines.
  65. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  66. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Simplify your language. 
 Is there a more direct way to write the same thing?
  67. NO DE CO NF ARGENTI NA T R AC Y

    O S B O R N @limedaring
  68. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  69. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Document with pictures.
  70. NO DE CO NF ARGENTI NA T R AC Y

    O S B O R N @limedaring
  71. NO DE CO NF ARGENTI NA T R AC Y

    O S B O R N @limedaring
  72. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  73. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring
  74. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Overwhelmed?
  75. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Overwhelmed? 1. Take a break.
  76. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Overwhelmed? 1. Take a break. 2. Have a friend review your writing.
  77. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring In conclusion… 
 (People are awesome and we want them to use our stuff.)
  78. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Remember that your readers have different backgrounds and experiences than you.
  79. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Be friendly and write like a human.
  80. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Simplify. (applies to length, word choice and complexity, layout, everything.)
  81. NO DE CO NF ARGENTI NA T R AC Y

    O S B O R N @limedaring
  82. NO DE CONF BUDAPE ST T R AC Y O

    S B O R N @limedaring Thank you! @limedaring
  83. NO DE CO NF ARGENTI NA T R AC Y

    O S B O R N @limedaring