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

8c5989329a85b590fecdb4f7a97cbe3a?s=128

Carolyn Stransky

May 13, 2019
Tweet

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

  52. None
  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