Beyond Words: Crafting User-Friendly Documentation
summary
Hands-on workshop that converts a vague README into a skimmable getting-started with numbered steps, a short intro stating outcomes, and a next-steps trail; shows a broken API spec fixed with allowed file types (CSV, JSON, Excel), auth details, sample responses and error codes; demos visuals created with draw.io/mermaid.js and advises alt text and contrast; recommends automating docs tickets and style checks via GitHub Actions, adding a feedback widget, and a checklist so documentation ships with each feature and cuts maintainer support load.
AI-written summary · about
chapters (9)
- 0:00Introduction and speaker background
- 1:05Why good documentation matters
- 9:34Analyzing bad user guides
- 17:58Simplifying technical language
- 21:32Using visuals effectively
- 26:51Gathering feedback for docs
- 33:10Common documentation mistakes
- 41:59Documentation checklist summary
- 47:04Q&A and closing remarks
related talks
28mImproving Your Documentation: A talk for developers who want to write stuff good
49mExplain Yourself! Documentation for Better Code
33mWhat The Doc?!?! How to Write and Read Documentation That Allows You To Get Sh*t Done!
56mEffective Documentation: The Key to Open Source Growth
21mWriting documentations that don't suck!
47mDocumentation Is Fine, Don't Worry
01h 01mRight the docs
26mPractice Makes Perfect: Write Accessible Documentation