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
   

   View Slide

2. Why do we write
   documentation?
   Tyner Blain bit.ly/goal-driven-docs
   

   View Slide

3. Tyner Blain bit.ly/use-case-docs
   USE CASE DRIVEN
   DOCUMENTATION
   

   View Slide

4. Tyner Blain bit.ly/goal-driven-docs
   

   View Slide

5. How to adjust the speed
   How to change the direction
   How to change the drill bit
   Tyner Blain bit.ly/goal-driven-docs
   

   View Slide

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
   

   View Slide

7. Who do we write
   documentation for?
   @carolstran
   

   View Slide

8. Humans
   @carolstran
   

   View Slide

9. @carolstran
   

   View Slide

10. bit.ly/slack-docs
    Slack API Portal
    

    View Slide

11. Making messages interactive
    Subscribing to Event Types
    Events API vs. RTM API
    Slack API Portal bit.ly/slack-docs
    

    View Slide

12. bit.ly/slack-docs
    

    View Slide

13. GOAL
    USE CASE
    Tyner Blain bit.ly/use-case-docs
    

    View Slide

14. FUNCTIONAL REQUIREMENT
    DESIGN
    IMPLEMENTATION
    GOAL
    USE CASE
    Tyner Blain bit.ly/use-case-docs
    

    View Slide

15. FUNCTIONAL REQUIREMENT
    DESIGN
    IMPLEMENTATION
    GOAL
    USE CASE
    Tyner Blain bit.ly/use-case-docs
    

    View Slide

16. FUNCTIONAL REQUIREMENT
    DESIGN
    IMPLEMENTATION
    GOAL
    USE CASE
    Tyner Blain bit.ly/use-case-docs
    

    View Slide

17. This is cool
    @carolstran
    

    View Slide

18. But it doesn’t happen
    @carolstran
    

    View Slide

19. JavaScript
    @carolstran
    

    View Slide

20. What’s going on?
    Why is this so confusing?
    Do people actually enjoy this?
    @carolstran
    

    View Slide

21. No one wants to read
    your docs
    @carolstran
    

    View Slide

22. No one wants to read
    your docs
    @carolstran
    

    View Slide

23. People don’t mind
    reading docs…
    @carolstran
    

    View Slide

24. … as long as they’re
    actually helpful
    @carolstran
    

    View Slide

25. bit.ly/EthanMcQuarrie-tweet
    Ethan McQuarrie
    

    View Slide

26. Killian McMahon bit.ly/kilmc-tweet
    

    View Slide

27. bit.ly/jetleigh-tweet
    Leigh Momii
    

    View Slide

28. bit.ly/jetleigh-tweet
    Leigh Momii
    

    View Slide

29. bit.ly/jetleigh-tweet
    Leigh Momii
    

    View Slide

30. If only developers
    cared about docs…
    @carolstran
    

    View Slide

31. If only developers
    cared about docs…
    @carolstran
    

    View Slide

32. Writing docs is only
    part of the job
    @carolstran
    

    View Slide

33. WRITING
    @carolstran
    

    View Slide

34. Insensitive language
    @carolstran
    

    View Slide

35. If the programmer wishes to
    uphold the invariant, he must
    satisfy the function’s preconditions
    

    View Slide

36. Problematic but
    common terms
    @carolstran
    

    View Slide

37. Master / Slave
    Blacklist / Whitelist
    

    View Slide

38. Think before you type
    @carolstran
    

    View Slide

39. Primary / Replica
    Denylist / Allowlist
    

    View Slide

40. bit.ly/alex-js
    

    View Slide

41. alex bit.ly/alex-js
    

    View Slide

42. Saying ‘simply’ or ‘easy’
    @carolstran
    

    View Slide

43. Don’t say it
    @carolstran
    

    View Slide

44. bit.ly/dont-say-simply
    Be specific
    Jim Fisher
    

    View Slide

45. bit.ly/dont-say-simply
    Be comparative
    Jim Fisher
    

    View Slide

46. bit.ly/dont-say-simply
    Be absolute
    Jim Fisher
    

    View Slide

47. bit.ly/dont-say-simply
    Show, don’t tell
    Jim Fisher
    

    View Slide

48. bit.ly/write-good
    

    View Slide

49. write-good *.md
    write good bit.ly/write-good
    

    View Slide

50. Bloated language
    @carolstran
    

    View Slide

51. Plain language
    @carolstran
    

    View Slide

52. View Slide

53. bit.ly/ashley-fronteers
    “No one has ever
    complained that something
    was too easy to read”
    Ashley Bischoff
    

    View Slide

54. Unexpected errors
    @carolstran
    

    View Slide

55. Address common errors
    @carolstran
    

    View Slide

56. What might happen
    Potential reasons why
    What to do next
    @carolstran
    

    View Slide

57. bit.ly/appleII-manual
    Apple Computer Inc
    

    View Slide

58. Django Girls bit.ly/django-girls-tut
    

    View Slide

59. You’re in too deep
    @carolstran
    

    View Slide

60. Everyone is a beginner
    at some point
    @carolstran
    

    View Slide

61. Take a step back
    @carolstran
    

    View Slide

62. CODE SNIPPETS
    @carolstran
    

    View Slide

63. Code snippets shouldn’t
    be screenshots
    @carolstran
    

    View Slide

64. bit.ly/mdn-code
    for inline
    MDN docs
    

    View Slide

65. MDN docs bit.ly/mdn-pre
    for blocks
    

    View Slide

66. bit.ly/md-cheatsheet
    Markdown Cheatsheet
    ```javascript
    

    View Slide

67. Watch for extra spaces
    @carolstran
    

    View Slide

68. Foo / Bar / Baz
    @carolstran
    

    View Slide

69. Meaningful placeholders
    @carolstran
    

    View Slide

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
    

    View Slide

71. var baz = [‘foo’, 'bar' ]
    

    View Slide

72. bit.ly/js-array-mdn
    var fruits =
    [‘apple’, ‘banana' ]
    MDN JS array docs
    

    View Slide

73. var array_name =
    [‘item1’, ‘item2’ ]
    

    View Slide

74. STRUCTURE
    @carolstran
    

    View Slide

75. Poorly defined structure
    @carolstran
    

    View Slide

76. Mindful structure
    @carolstran
    

    View Slide

77. Explain the feature
    Describe the use case(s)
    Recommend tooling
    @carolstran
    

    View Slide

78. @carolstran
    

    View Slide

79. @carolstran
    

    View Slide

80. bit.ly/a11yfore
    HTML - Hypertext
    Markup Language
    Laura Kalbag
    

    View Slide

81. > Some quote
    ---
    Markdown Cheatsheet bit.ly/md-cheatsheet
    

    View Slide

82. > Some quote
    ---
    Markdown Cheatsheet bit.ly/md-cheatsheet
    

    View Slide

83. > Some quote
    ---
    Markdown Cheatsheet bit.ly/md-cheatsheet
    

    View Slide

84. bit.ly/a11y-html
    h1
    nav
    aside
    lang=“"
    Manuel Matuzovic
    

    View Slide

85. bit.ly/react-gs
    React
    

    View Slide

86. bit.ly/react-gs
    React
    

    View Slide

87. bit.ly/shopify-dp
    Shopify Developer Portal
    

    View Slide

88. Skip links
    @carolstran
    

    View Slide

89. twilio.com/docs
    Twilio
    

    View Slide

90. Twilio twilio.com/docs
    

    View Slide

91. developer.mozilla.org
    MDN
    

    View Slide

92. A11Y
    @carolstran
    

    View Slide

93. Documentation is left
    out of the conversation
    @carolstran
    

    View Slide

94. “Documentation is for
    developers”
    

    View Slide

95. StackOverflow Developer Survey bit.ly/so-devsurvey
    One out of every 200
    software developers is
    blind or hard of sight
    

    View Slide

96. bit.ly/fcc-florian
    Florian Beijers, freeCodeCamp
    “The tutorials were
    undoubtedly good, but were
    completely unreadable for me”
    

    View Slide

97. This is our
    responsibility
    @carolstran
    

    View Slide

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”
    

    View Slide

99. Test our docs for
    accessibility
    @carolstran
    

    View Slide

100. deque.com/axe
     

     View Slide

101. bit.ly/vue-v2
     Vue.js Introduction
     

     View Slide

102. wave.webaim.org
     

     View Slide

103. bit.ly/slack-integrations
     Slack API
     

     View Slide

104. Create an accessibility
     policy for your docs
     @carolstran
     

     View Slide

105. bit.ly/oracle-docs-a11y
     

     View Slide

106. bit.ly/mdn-a11y-hack
     Host an a11y hackathon
     for your docs
     Hack on MDN
     

     View Slide

107. FINAL NOTE
     @carolstran
     

     View Slide

108. Accuracy and consistency
     @carolstran
     

     View Slide

109. Aim to be honest,
     helpful and human
     @carolstran
     

     View Slide