Developer’s Torment: The Documentation
summary
Recommendation: use EventStorming to build a ubiquitous language in a half-day workshop; capture architecture choices as Architecture Decision Records with context, status and consequences so future reviewers know why decisions were valid then; adopt the ADR tools CLI, text-based docs (AsciiDoc, PlantUML), and repo naming/README conventions so services, traces and endpoints are discoverable; minimize code comments, favor small entry APIs, consistent naming and sane defaults to make code self-documenting.
AI-written summary · about
chapters (10)
- 0:00Start
- 6:02What to document?
- 7:31Decision Sustainability Piramid (DSP™)
- 8:41EventStorming
- 17:16Example: Data Abstraction Model
- 25:18Discoverability is better
- 29:13Consistency is the king!
- 31:38Usability 101
- 32:03LEMES of business and domain
- 33:20Developer's Torment:: The Documentation:: Links
related talks
29mStop Documentation Debt: Industrialize Your ADRs and READMEs with Spec-kit
51mDocumenting and Communicating Modern Software Architectures
39mWe're Agile, we don't do documentation
46mBest Practices for Keeping Architecture Documentation Up to Date
46mSave a Dev, Write Documentation!
47mDocumentation Is Fine, Don't Worry
35mThe practical implementation of Documentation as Code
28mImproving Your Documentation: A talk for developers who want to write stuff good