On Writing Friendly and Welcoming Documentation / NodeConf Budapest

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