Humanizing Your Documentation - Full Talk

A talk focused on how to create and maintain use case-driven documentation.

Current deck from: Beyond Tellerrand Düsseldorf 2019
Recording: http://bit.ly/btconf-hyd

Transcript

1. Humanizing Your Documentation @carolstran
2. Why do we write documentation? Tyner Blain bit.ly/goal-driven-docs
3. Tyner Blain bit.ly/use-case-docs USE CASE DRIVEN DOCUMENTATION
4. Tyner Blain bit.ly/goal-driven-docs
5. How to adjust the speed How to change the direction How to change the drill bit Tyner Blain bit.ly/goal-driven-docs
6. How to drill a hole in a flat surface How to select the right screw How to stir paint with your drill Tyner Blain bit.ly/goal-driven-docs
7. Who do we write documentation for? @carolstran
8. Humans @carolstran
9. @carolstran
10. bit.ly/slack-docs Slack API Portal
11. Making messages interactive Subscribing to Event Types Events API vs. RTM API Slack API Portal bit.ly/slack-docs
12. bit.ly/slack-docs
13. GOAL USE CASE Tyner Blain bit.ly/use-case-docs
14. FUNCTIONAL REQUIREMENT DESIGN IMPLEMENTATION GOAL USE CASE Tyner Blain bit.ly/use-case-docs
15. FUNCTIONAL REQUIREMENT DESIGN IMPLEMENTATION GOAL USE CASE Tyner Blain bit.ly/use-case-docs
16. FUNCTIONAL REQUIREMENT DESIGN IMPLEMENTATION GOAL USE CASE Tyner Blain bit.ly/use-case-docs
17. This is cool @carolstran
18. But it doesn’t happen @carolstran
19. JavaScript @carolstran
20. What’s going on? Why is this so confusing? Do people actually enjoy this? @carolstran
21. No one wants to read your docs @carolstran
22. No one wants to read your docs @carolstran
23. People don’t mind reading docs… @carolstran
24. … as long as they’re actually helpful @carolstran
25. bit.ly/EthanMcQuarrie-tweet Ethan McQuarrie
26. Killian McMahon bit.ly/kilmc-tweet
27. bit.ly/jetleigh-tweet Leigh Momii
28. bit.ly/jetleigh-tweet Leigh Momii
29. bit.ly/jetleigh-tweet Leigh Momii
30. If only developers cared about docs… @carolstran
31. If only developers cared about docs… @carolstran
32. Writing docs is only part of the job @carolstran
33. WRITING @carolstran
34. Insensitive language @carolstran
35. If the programmer wishes to uphold the invariant, he must satisfy the function’s preconditions
36. Problematic but common terms @carolstran
37. Master / Slave Blacklist / Whitelist
38. Think before you type @carolstran
39. Primary / Replica Denylist / Allowlist
40. bit.ly/alex-js
41. alex bit.ly/alex-js
42. Saying ‘simply’ or ‘easy’ @carolstran
43. Don’t say it @carolstran
44. bit.ly/dont-say-simply Be specific Jim Fisher
45. bit.ly/dont-say-simply Be comparative Jim Fisher
46. bit.ly/dont-say-simply Be absolute Jim Fisher
47. bit.ly/dont-say-simply Show, don’t tell Jim Fisher
48. bit.ly/write-good
49. write-good *.md write good bit.ly/write-good
50. Bloated language @carolstran
51. Plain language @carolstran
53. bit.ly/ashley-fronteers “No one has ever complained that something was too easy to read” Ashley Bischoff
54. Unexpected errors @carolstran
55. Address common errors @carolstran
56. What might happen Potential reasons why What to do next @carolstran
57. bit.ly/appleII-manual Apple Computer Inc
58. Django Girls bit.ly/django-girls-tut
59. You’re in too deep @carolstran
60. Everyone is a beginner at some point @carolstran
61. Take a step back @carolstran
62. CODE SNIPPETS @carolstran
63. Code snippets shouldn’t be screenshots @carolstran
64. bit.ly/mdn-code <code> for inline MDN <code> docs
65. MDN <pre> docs bit.ly/mdn-pre <pre> for blocks
66. bit.ly/md-cheatsheet Markdown Cheatsheet ```javascript
67. Watch for extra spaces @carolstran
68. Foo / Bar / Baz @carolstran
69. Meaningful placeholders @carolstran
70. bit.ly/elibelly-reply “We can have variable names that are both meaningful and generic that expose their purpose via their semantics” Eli Schütze Ramirez
71. var baz = [‘foo’, 'bar' ]
72. bit.ly/js-array-mdn var fruits = [‘apple’, ‘banana' ] MDN JS array docs
73. var array_name = [‘item1’, ‘item2’ ]
74. STRUCTURE @carolstran
75. Poorly defined structure @carolstran
76. Mindful structure @carolstran
77. Explain the feature Describe the use case(s) Recommend tooling @carolstran
78. @carolstran
79. @carolstran
80. bit.ly/a11yfore HTML - Hypertext Markup Language Laura Kalbag
81. > Some quote <blockquote> --- <hr> Markdown Cheatsheet bit.ly/md-cheatsheet
82. > Some quote <blockquote> --- <hr> Markdown Cheatsheet bit.ly/md-cheatsheet
83. > Some quote <blockquote> --- <hr> Markdown Cheatsheet bit.ly/md-cheatsheet
84. bit.ly/a11y-html h1 nav aside lang=“" Manuel Matuzovic
85. bit.ly/react-gs React
86. bit.ly/react-gs React
87. bit.ly/shopify-dp Shopify Developer Portal
88. Skip links @carolstran
89. twilio.com/docs Twilio
90. Twilio twilio.com/docs
91. developer.mozilla.org MDN
92. A11Y @carolstran
93. Documentation is left out of the conversation @carolstran
94. “Documentation is for developers”
95. StackOverflow Developer Survey bit.ly/so-devsurvey One out of every 200 software developers is blind or hard of sight
96. bit.ly/fcc-florian Florian Beijers, freeCodeCamp “The tutorials were undoubtedly good, but were completely unreadable for me”
97. This is our responsibility @carolstran
98. Anne Gibson, independent consultant bit.ly/pfa-anne “We may or may not be responsible for writing the HTML, but if the developers we’re working with don’t produce semantic structure, then they’re not actually representing the structures that we’re building in our designs”
99. Test our docs for accessibility @carolstran
100. deque.com/axe
101. bit.ly/vue-v2 Vue.js Introduction
102. wave.webaim.org
103. bit.ly/slack-integrations Slack API
104. Create an accessibility policy for your docs @carolstran
105. bit.ly/oracle-docs-a11y
106. bit.ly/mdn-a11y-hack Host an a11y hackathon for your docs Hack on MDN
107. FINAL NOTE @carolstran
108. Accuracy and consistency @carolstran
109. Aim to be honest, helpful and human @carolstran