The Curse of Documentation
summary
Claim: most documentation is “cursed” because examples and an API reference (here a gallery plus about 105 functions) don’t show how pieces fit together, and a focused user guide unblocks users. Demonstration uses Great Tables and Pointblank, emphasizing three strategic components—structure, format, style—and a five-step recipe: collect WRST examples, map concepts into a concept matrix, sequence an end-to-end onboarding, detail shared patterns, and validate with a workshop. Also notes use of quartodoc for API pages.
AI-written summary · about
chapters (13)
- 0:00Cursed documentation intro
- 1:28Problem with current docs
- 2:31Gallery vs API reference
- 4:23What a user guide solves
- 6:57Five steps to user guide
- 8:46Step 1: Collect WRST examples
- 11:19Step 2: Scope strategic concepts
- 13:32Step 3: Sequence onboarding
- 14:37Step 4: Detail remaining concepts
- 16:06Concept matrices for patterns
- 18:15Step 5: Draft a workshop
- 18:45Q&A: Too much documentation
- 19:07Q&A: Quartodoc and pkgdown
related talks
01h 24mWriting Documentation - Practices and Theory
53mThe Emperor Has No Docs
48mBeyond Words: Crafting User-Friendly Documentation
31mWhat nobody tells you about documentation
43mThe Docs Are Fine, Don't Worry
39mDevelopers Documentation: your hidden strength
46mThe 7 Deadly Sins of Documentation
01h 02m“How to Write Effective Documentation for C++ Libraries..."