Graphs, not trees: A ground-up approach to fixing a docs site.
summary
Thesis: major IA improvements come from ground-up fixes rather than jumping to top-level reorgs. Practical moves include run a link checker, fix broken links and intros, enforce style rules, and instrument pages with examples, diagrams and templates. Observe readers via usability sessions, forum posts, YouTube sessions and server-side tree listings to find high-traffic “Shibuya” pages. Gradually separate content by purpose (separating docs into types), add tutorials and tests, and use iterative small wins to build trust and enable safe higher‑level changes.
AI-written summary · about
chapters (30)
- 0:00Welcome
- 1:06Thesis: Ground-up docs fix
- 2:55Top-down urban planning failures
- 6:23Reader-centered vs top-down
- 7:06Trees vs graphs in docs
- 9:36Reader navigation as graph
- 10:41Writer personas and pressure
- 12:06Ground-level observation essential
- 12:28Gradual high-level improvements
- 12:48Reading docs as beginner
- 14:15Mapping reader workflows
- 15:18Shearing layers of docs
- 16:22Fixing potholes first
- 17:46Improving page introductions
- 18:30Learning tools and culture
- 20:16Linking pages for flow
- 20:58Separating docs by purpose
- 21:42Addressing reader frustrations
- 22:46Testing docs with readers
- 24:10Refined and beautiful docs
- 25:39Deep writing and concepts
- 26:40Advocating user-centered design
- 27:42Iterative docs maturation
- 28:46Building expertise
- 30:33Q&A: Info architecture
- 32:18Q&A: Usability testing
- 33:22Q&A: Link density balance
- 35:06Q&A: Convincing organizations
- 37:54Q&A: Reframing legacy docs
- 39:21Closing
related talks
20mStop writing docs; Start helping
37mTaking a step back: Analysing your documentation
28mStop writing docs; start helping!
21mBuilding navigation for your doc site: 5 best practices
29mHumanizing Your Documentation
51mWriting the Darn Docs
01h 24mWriting Documentation - Practices and Theory
46mSave a Dev, Write Documentation!