Humanizing Your Documentation
Last given at React Finland on May 28, 2020.
Readings
📖 Goal-Driven Documentation
An article by Tyner Blain outlining how to write docs that focus on user goals, including the full drill example.
📖 Use Case Driven Documentation
Another article by Tyner Blain, this time introducing the concept of use case driven docs and where it fits in the development cycle.
💻 <code>: The Inline Code element on MDN
💻 <pre>: The Preformatted Text element on MDN
💻 The JavaScript Array class on MDN
Linters and Tools
⚠️ Linters aren't a replacement for human editing!
📕 Self-Defined Dictionary
Created by Tatiana Mac to provide more inclusive and holistic definitions to reflect diverse perspectives.
🛠 AlexJS
A linter for your Markdown files that catches insensitive and inconsiderate writing.
🛠 write-good
A linter for English prose, you can also write extensions to catch specific words or phrases your team uses often.
🛠 Hemingway Editor
A web app (and linter) that highlights problematic words/sentences and offers suggestions. You want to aim for a Grade 8 reading level or lower.
Documentation Examples
For use case-focused tutorials:
📲 Slack API Portal
For addressing errors:
🍏 Apple II Basic Programming Manual
🐍 Django Girls Tutorial
For transparency:
💼 ReasonML - Converting from JS
Quoted Tweets
🐦 @EthanMcQuarrie
🐦 @kilmc
🐦 @jetleigh
🐦 @sarah_edo
🐦 @elibelly
🐦 @andrestaltz
Mentioned Talks
🎙 Lucie La Naour on the Write the Docs Podcast
How to write inclusive tech documentation.
🎤 Jim Fisher at Write the Docs London
A look at why we use terms like "simply" and how we can avoid it.
🎤 Laura Kalbag at A11yclub Berlin
Discussing how developers, designers, etc use the term "users" to other the people using their products.
🎤 Ashley Bischoff at Fronteers
Straightforward techniques and approaches to plain language in documentation.
Like my work?
Let me send updates to your inbox (and one day, a newsletter).
Unsubscribe anytime. No spam 🤖