Writing So Your Words Are Read — Write the Docs

Transcript

1. WRITE THE DOCS T R AC Y O S B O R N @limedaring Writing So Your Words Are Read 
 How to write documentation that everyone would want to read and can understand.
2. WRITE THE DOCS T R AC Y O S B O R N @limedaring Hi, I’m Tracy! @limedaring (daring, not darling)
3. WRITE THE DOCS T R AC Y O S B O R N @limedaring
4. WRITE THE DOCS T R AC Y O S B O R N @limedaring
5. WRITE THE DOCS T R AC Y O S B O R N @limedaring
6. WRITE THE DOCS T R AC Y O S B O R N @limedaring
7. WRITE THE DOCS T R AC Y O S B O R N @limedaring
8. WRITE THE DOCS T R AC Y O S B O R N @limedaring
9. WRITE THE DOCS T R AC Y O S B O R N @limedaring
10. WRITE THE DOCS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
11. WRITE THE DOCS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
12. WRITE THE DOCS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
13. WRITE THE DOCS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
14. WRITE THE DOCS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
15. WRITE THE DOCS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
16. WRITE THE DOCS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
17. WRITE THE DOCS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
18. WRITE THE DOCS T R AC Y O S B O R N @limedaring
19. WRITE THE DOCS T R AC Y O S B O R N @limedaring Better documentation = More users. Less support requests. More contributors.
20. WRITE THE DOCS T R AC Y O S B O R N @limedaring We’re chatting content, not design 
 (and definitely not grammar.)
21. WRITE THE DOCS T R AC Y O S B O R N @limedaring How do we make our documentation easy to read and enjoyable?
22. WRITE THE DOCS T R AC Y O S B O R N @limedaring The basics of friendly and welcoming writing. 
 (Let’s throw some best practices out the window.)
23. WRITE THE DOCS T R AC Y O S B O R N @limedaring Remember — 
 your readers aren’t you.
24. WRITE THE DOCS T R AC Y O S B O R N @limedaring Write like a human, not a machine.
25. WRITE THE DOCS T R AC Y O S B O R N @limedaring
26. WRITE THE DOCS T R AC Y O S B O R N @limedaring
27. WRITE THE DOCS T R AC Y O S B O R N @limedaring But… avoid cultural references since they won’t translate.
28. WRITE THE DOCS T R AC Y O S B O R N @limedaring
29. WRITE THE DOCS 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.
30. WRITE THE DOCS T R AC Y O S B O R N @limedaring Try personas — create a character and write for them.
31. WRITE THE DOCS 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?”
32. WRITE THE DOCS T R AC Y O S B O R N @limedaring
33. WRITE THE DOCS T R AC Y O S B O R N @limedaring This document discusses using various kinds of authentication with Requests. Many web services require authentication, and there are many different types. Below, we outline various forms of authentication available in Requests, from the simple to the complex.
34. WRITE THE DOCS T R AC Y O S B O R N @limedaring
35. WRITE THE DOCS T R AC Y O S B O R N @limedaring Remember that terms that are obvious might not be obvious to others.
36. WRITE THE DOCS T R AC Y O S B O R N @limedaring
37. WRITE THE DOCS T R AC Y O S B O R N @limedaring “Cream the butter”
38. WRITE THE DOCS T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird”
39. WRITE THE DOCS T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites”
40. WRITE THE DOCS T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat”
41. WRITE THE DOCS 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”
42. WRITE THE DOCS 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. WRITE THE DOCS T R AC Y O S B O R N @limedaring Link anything that you 
 don’t want to explain.
44. WRITE THE DOCS T R AC Y O S B O R N @limedaring
45. WRITE THE DOCS T R AC Y O S B O R N @limedaring Teach — don’t tell. http://stevelosh.com/blog/2013/09/teach-dont-tell/
46. WRITE THE DOCS T R AC Y O S B O R N @limedaring Reading the source works for someone already familiar with your project. Your documentation needs to get them to that point.
47. WRITE THE DOCS T R AC Y O S B O R N @limedaring
48. WRITE THE DOCS T R AC Y O S B O R N @limedaring Dumb things down without 
 making them dumb.
49. WRITE THE DOCS T R AC Y O S B O R N @limedaring
50. WRITE THE DOCS T R AC Y O S B O R N @limedaring
51. WRITE THE DOCS T R AC Y O S B O R N @limedaring
52. WRITE THE DOCS T R AC Y O S B O R N @limedaring
53. WRITE THE DOCS T R AC Y O S B O R N @limedaring Use gender-neutral language.
54. WRITE THE DOCS T R AC Y O S B O R N @limedaring
55. WRITE THE DOCS 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/
56. WRITE THE DOCS T R AC Y O S B O R N @limedaring The basics of 
 writing clearly. 
 (Shorter is better, yo.)
57. WRITE THE DOCS T R AC Y O S B O R N @limedaring Cut down your content. 
 Two to three sentences per line.
58. WRITE THE DOCS T R AC Y O S B O R N @limedaring Break into bullets and use lots of headers. Make it easy to skim.
59. WRITE THE DOCS T R AC Y O S B O R N @limedaring Use italics and bolding to 
 break up paragraphs.
60. W EB DEVCON T RAC Y O S B OR 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.
61. W EB DEVCON T RAC Y O S B OR 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.
62. W EB DEVCON T RAC Y O S B OR 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. WRITE THE DOCS 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?
64. WRITE THE DOCS T R AC Y O S B O R N @limedaring
65. WRITE THE DOCS T R AC Y O S B O R N @limedaring Don’t forget your headlines.
66. W EB DEVCON T RAC Y O S B OR N @limedaring
67. W EB DEVCON T RAC Y O S B OR N @limedaring
68. WRITE THE DOCS T R AC Y O S B O R N @limedaring Mark up your code snippets to make sure they’re styled differently.
69. WRITE THE DOCS T R AC Y O S B O R N @limedaring
70. WRITE THE DOCS T R AC Y O S B O R N @limedaring
71. WRITE THE DOCS T R AC Y O S B O R N @limedaring Add filenames to code blocks 
 if it makes sense.
72. WRITE THE DOCS T R AC Y O S B O R N @limedaring
73. WRITE THE DOCS T R AC Y O S B O R N @limedaring
74. WRITE THE DOCS T R AC Y O S B O R N @limedaring Document with pictures.
75. WRITE THE DOCS T R AC Y O S B O R N @limedaring
76. WRITE THE DOCS T R AC Y O S B O R N @limedaring
77. WRITE THE DOCS 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. WRITE THE DOCS T R AC Y O S B O R N @limedaring Remember that your readers have different backgrounds and experiences than you.
79. WRITE THE DOCS T R AC Y O S B O R N @limedaring Thank you! @limedaring