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

💻 Markdown Cheatsheet

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.