Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Resources from my talk on humanizing your docs ✒️

Humanizing Your Documentation

🖥 PDF Slides 📝 Abstract 📹 Video

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.

Linters and Tools

🛠 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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.