Humanizing Your Documentation
Last given at React Finland on May 28, 2020.
📖 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
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.
A linter for your Markdown files that catches insensitive and inconsiderate writing.
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.
For use case-focused tutorials:
📲 Slack API Portal
💼 ReasonML - Converting from JS
🎙 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?
Subscribe for updates and the (very occasional) newsletter. Unsubscribe anytime. No spam 🤖