Humanizing Your Documentation
summary
Argues for use-case driven documentation with concrete examples (a drill, Slack pages) and shows how restructuring docs around user goals prevents confusion; demonstrates clearer error text that explains what happened why and next steps; recommends tools like Alex Jess linter to catch insensitive terms and "simply" and Hemingway Editor to lower reading level; cites 92 million GitHub hits for "simply" as evidence of the problem and points to Contentful's style goal to be honest helpful and human.
AI-written summary · about
chapters (25)
- 0:00Intro
- 0:45DOCUMENTATION?
- 2:05HOW TO CHANGE THE DIRECTION
- 2:47HOW TO SELECT THE RIGHT SCREW FOR FASTENING ITEMS
- 5:11FUNCTIONAL REQUIREMENT
- 7:22WHAT IS GOING ON?
- 7:40DO PEOPLE ACTUALLY ENJOY THIS?
- 11:35DISORIENTING
- 11:48ALIENATING
- 12:43POORLY DEFINED STRUCTURE
- 13:25MINDFUL STRUCTURE
- 13:40DESCRIBE THE USE CASE(S)
- 14:15UNEXPECTED ERRORS
- 15:38ADDRESS COMMON ERRORS
- 17:28USE MEANINGFUL PLACEHOLDERS
- 18:43INSENSITIVE LANGUAGE
- 19:05IF THE PROGRAMMER WISHES TO UPHOLD THE INVARIANT, HE MUST SATISFY THE FUNCTION'S PRECONDITIONS
- 19:36BLACKLIST / WHITELIST
- 21:46DEVELOPING A PLUGIN IS SIMPLE. THE ONLY KNOWLEDGE NECESSARY TO WRITE A PLUGIN IS BASIC COMMAND-LINE SKILLS AND BASIC KNOWLEDGE OF THE GO PROGRAMMING LANGUAGE
- 22:57BLOATED LANGUAGE
- 23:49PLAIN LANGUAGE
- 25:09YOUR PRODUCT ISN'T THE RIGHT FIT
- 25:39BE TRANSPARENT
- 26:56ACCURACY AND CONSISTENCY
- 27:08AIM TO BE HONEST HELPFUL & HUMAN
