$30 off During Our Annual Pro Sale. View Details »

Humanizing Your Documentation - Full Talk

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

Carolyn Stransky

May 13, 2019
Tweet

More Decks by Carolyn Stransky

Other Decks in Technology

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