Documentation Is Fine, Don't Worry
summary
Presents a documentation workflow using an arc42 template together with docs-as-code and open-source tools to produce reviewable docs quickly. It combines Diátaxis to separate user vs reference content, OpenAPI Generator with Redoc/Swagger for API sites, Compodoc for Angular component maps, schemaSpy for database diagrams, PlantUML/mermaid/C4 for diagrams, and Structurizr to generate multiple views from one model. Applies this stack to a ticketing app, producing about half of the 12-section template and most diagrams to create a usable documentation skeleton in under a week.
AI-written summary · about
chapters (9)
- 0:00Introduction
- 3:35Arc 42 template
- 10:41API docs with OpenAPI
- 17:24Diagrams with Structurizer
- 25:29Front-end docs with Compodoc
- 30:44Cross-cutting concepts
- 36:22Risk and technical debt
- 41:38Other templates and best practices
- 43:25Conclusion
related talks
43mThe Docs Are Fine, Don't Worry
44mPushing documentation (so it doesn't hurt anymore)
50mContinuous and Automated Documentation Docs As Code in Practice
48mBeyond Words: Crafting User-Friendly Documentation
47mEngineering Documentation
35mOpenAPI for Documentarians
35mThe practical implementation of Documentation as Code
47mDocumentation, it is alive!