Writing So Your Words Are Read — Abstractions

Transcript

1. ABSTRACTIONS 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. ABSTRACTIONS T R AC Y O S B O R N @limedaring Hi, I’m Tracy! @limedaring (daring, not darling)
3. ABSTRACTIONS T R AC Y O S B O R N @limedaring
4. ABSTRACTIONS T R AC Y O S B O R N @limedaring
5. ABSTRACTIONS T R AC Y O S B O R N @limedaring
6. ABSTRACTIONS T R AC Y O S B O R N @limedaring
7. ABSTRACTIONS T R AC Y O S B O R N @limedaring
8. ABSTRACTIONS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
9. ABSTRACTIONS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
10. ABSTRACTIONS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
11. ABSTRACTIONS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
12. ABSTRACTIONS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
13. ABSTRACTIONS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
14. ABSTRACTIONS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
15. ABSTRACTIONS T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
16. ABSTRACTIONS T R AC Y O S B O R N @limedaring
17. ABSTRACTIONS T R AC Y O S B O R N @limedaring Better documentation = More users. Less support requests. More contributors.
18. ABSTRACTIONS T R AC Y O S B O R N @limedaring We’re chatting content, not design 
 (and definitely not grammar.)
19. ABSTRACTIONS T R AC Y O S B O R N @limedaring Most of these tips work 
 for all writing
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. FLU EN T CO NFER ENC E T RAC Y OS B OR N @limedaring
23. FLU EN T CO NFER ENC E T RAC Y OS B OR N @limedaring
24. FLU EN T CO NFER ENC E T RAC Y OS B OR N @limedaring
25. ABSTRACTIONS 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?
26. ABSTRACTIONS 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.)
27. ABSTRACTIONS T R AC Y O S B O R N @limedaring Remember — 
 your readers aren’t you.
28. ABSTRACTIONS T R AC Y O S B O R N @limedaring
29. ABSTRACTIONS T R AC Y O S B O R N @limedaring
30. ABSTRACTIONS T R AC Y O S B O R N @limedaring
31. ABSTRACTIONS T R AC Y O S B O R N @limedaring Write like a human, not a machine.
32. ABSTRACTIONS T R AC Y O S B O R N @limedaring
33. ABSTRACTIONS T R AC Y O S B O R N @limedaring
34. ABSTRACTIONS T R AC Y O S B O R N @limedaring But… avoid cultural references since they won’t translate.
35. ABSTRACTIONS T R AC Y O S B O R N @limedaring
36. ABSTRACTIONS 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.
37. ABSTRACTIONS T R AC Y O S B O R N @limedaring Try personas — create a character and write for them.
38. ABSTRACTIONS 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?”
39. ABSTRACTIONS T R AC Y O S B O R N @limedaring
40. ABSTRACTIONS 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.
41. ABSTRACTIONS T R AC Y O S B O R N @limedaring
42. ABSTRACTIONS T R AC Y O S B O R N @limedaring Remember that terms that are obvious might not be obvious to others.
43. ABSTRACTIONS T R AC Y O S B O R N @limedaring
44. ABSTRACTIONS T R AC Y O S B O R N @limedaring “Cream the butter”
45. ABSTRACTIONS T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird”
46. ABSTRACTIONS T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites”
47. ABSTRACTIONS T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat”
48. ABSTRACTIONS 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”
49. ABSTRACTIONS 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”
50. ABSTRACTIONS T R AC Y O S B O R N @limedaring Link anything that you 
 don’t want to explain.
51. ABSTRACTIONS T R AC Y O S B O R N @limedaring
52. ABSTRACTIONS 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/
53. ABSTRACTIONS T R AC Y O S B O R N @limedaring The son says: “Hey Dad, you said you were going to teach me how to drive after school today. Are we still going to do that?” The father, without looking up from his iPad, replies: “Of course, son. The car is in the garage and I laid out a set of wrenches on the workbench. Take the car apart and look at each piece, then put it back together. Once you’ve done that I’ll take you to the DMV for your driving test.”
54. ABSTRACTIONS 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.
55. ABSTRACTIONS T R AC Y O S B O R N @limedaring
56. ABSTRACTIONS T R AC Y O S B O R N @limedaring Dumb things down 
 (without making them dumb.)
57. ABSTRACTIONS T R AC Y O S B O R N @limedaring
58. ABSTRACTIONS T R AC Y O S B O R N @limedaring
59. ABSTRACTIONS T R AC Y O S B O R N @limedaring
60. ABSTRACTIONS T R AC Y O S B O R N @limedaring
61. ABSTRACTIONS T R AC Y O S B O R N @limedaring Use gender-neutral language.
62. ABSTRACTIONS T R AC Y O S B O R N @limedaring
63. ABSTRACTIONS 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/
64. ABSTRACTIONS T R AC Y O S B O R N @limedaring The basics of 
 writing clearly. 
 (Shorter is better, yo.)
65. ABSTRACTIONS T R AC Y O S B O R N @limedaring Cut down your content. 
 Two to three sentences per paragraph.
66. ABSTRACTIONS T R AC Y O S B O R N @limedaring Break into bullets and use lots of headers. Make it easy to skim.
67. ABSTRACTIONS T R AC Y O S B O R N @limedaring Use italics and bolding to 
 break up paragraphs.
68. ABSTRACTIONS 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.
69. ABSTRACTIONS 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.
70. ABSTRACTIONS 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.
71. ABSTRACTIONS T R AC Y O S B O R N @limedaring Don’t forget your headlines.
72. ABSTRACTIONS 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. #talkpay
73. ABSTRACTIONS 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. #talkpay
74. ABSTRACTIONS 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?
75. ABSTRACTIONS T R AC Y O S B O R N @limedaring
76. ABSTRACTIONS T R AC Y O S B O R N @limedaring Mark up your code snippets to make sure they’re styled differently.
77. ABSTRACTIONS T R AC Y O S B O R N @limedaring
78. ABSTRACTIONS T R AC Y O S B O R N @limedaring
79. ABSTRACTIONS T R AC Y O S B O R N @limedaring Add filenames to code blocks 
 if it makes sense.
80. ABSTRACTIONS T R AC Y O S B O R N @limedaring
81. ABSTRACTIONS T R AC Y O S B O R N @limedaring
82. ABSTRACTIONS T R AC Y O S B O R N @limedaring Document with pictures.
83. ABSTRACTIONS T R AC Y O S B O R N @limedaring
84. ABSTRACTIONS T R AC Y O S B O R N @limedaring
85. ABSTRACTIONS T R AC Y O S B O R N @limedaring In conclusion… 
 (People are awesome and we want them to use our stuff.)
86. ABSTRACTIONS T R AC Y O S B O R N @limedaring Remember that your readers have different backgrounds and experiences than you.
87. ABSTRACTIONS T R AC Y O S B O R N @limedaring Be friendly and write like a human.
88. ABSTRACTIONS T R AC Y O S B O R N @limedaring Simplify. (applies to length, word choice and complexity, layout, everything.)
89. ABSTRACTIONS T R AC Y O S B O R N @limedaring Thank you! @limedaring