To document, or not document that is the question
summary
Argues that complex software rarely survives with zero docs and that typically 15–25% of system knowledge lives only in documents and conversations, so teams must keep a small, evolving set: a documentation roadmap, a spiral cookbook of how‑tos and runnable examples, and design notebooks linking to patterns and source. Builds a prototype typed wiki with transclusion, version travel, scaffolding, content assist and team subscriptions as a Dokuwiki plugin and reports it as functional but still under development.
AI-written summary · about
chapters (23)
- 0:00Intro
- 2:38Software development
- 3:55Knowledge acquisition
- 6:32Understanding = docs + conversations
- 7:23Knowledge evolution spiral
- 8:41Balancing agility & discipline
- 9:28Inspect & adapt
- 10:55Software documentation
- 11:58Minimalist Instruction
- 12:46Agile Modeling
- 16:37Core practices
- 18:39Additional practices
- 19:35Internal vs External Documentation
- 20:59A lot of documents...
- 22:24Patterns
- 26:20Example: JUnit
- 29:35Heterogeneous documents
- 30:51Single source approach
- 31:17Multiple source approach
- 31:55XSDoc Wiki
- 32:36Weaki: a weakly typed wiki
- 32:53Weaki: key features
- 34:10Weaki for DokuWiki (under development...)
related talks
39mWe're Agile, we don't do documentation
26mWe're Agile, We Don't Do Documentation
40mDocumentation as User Experience
38mThe Stuff You Don't Want to Write... Documentation
45mDocs or it didn't happen!
01h 24mWriting Documentation - Practices and Theory
31mWhat nobody tells you about documentation
35mThe practical implementation of Documentation as Code