The State of Community Documentation
summary
Scraped every README from about 5,000 add-ons and finds README clutter dominated by blueprint and contribution boilerplate, misleading install/run instructions, and unnecessary code samples (transforms appear in many examples though not required). Automated checks using retext and Alex flag 995 unhelpful cases (0.07% of words) and 2,359 inconsiderate instances. Demonstrates ember-cli-addon-docs plus a prototype CLI called nice-docs that runs these linters and reports issues so maintainers can fix docs; the tool works but remains rough.
AI-written summary · about
chapters (8)
- 0:00Introduction and speaker
- 1:32Why community docs matter
- 4:45State of Ember add-ons
- 12:15Analysis of README patterns
- 17:48Unhelpful and inconsiderate writing
- 24:40Tools for inclusive docs
- 26:26How to improve documentation
- 29:18Summary and thanks
related talks
48mBeyond Words: Crafting User-Friendly Documentation
45mDocs or it didn't happen!
24mEscaping the Curse of Outdated Docs
43mUseful and Beautiful Developer Docs and How to Create Them
39mDevelopers Documentation: your hidden strength
52mTechnically Speaking: improve your code with documentation
46mSave a Dev, Write Documentation!
38mDocumentation Templates: A Helpful Aid or an Obstacle