Humanizing Your Documentation

Last given at BeJS on May 12, 2023.

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!

🛠 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.

🛠️ Vale
Impress all of your technical writer friends!

🛠 Hemingway Editor
A web app 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 glossaries:
🐍 Python3 Glossary
📘 ReadMe Glossary Docs

For transparency:
⚛️ Create a New React App (Legacy)

Quoted Tweets

🐦 @EthanMcQuarrie
🐦 @kilmc
🐦 @jetleigh
🐦 @elibelly

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.

🎤 Ashley Bischoff at Fronteers
Straightforward techniques and approaches to plain language in documentation.

Bonus

⭐️ Not mentioned explicitly in the talk, but Write the Docs is a lovely community and knowledge base to help you write better documentation and discuss these topics with other people who care.