Continuous and Automated Documentation Docs As Code in Practice
summary
Advocates treating docs like code: store text and diagrams in git, version them with releases, and run Asciidoctor-based builds in CI to produce HTML/PDF and slides. Recommends Asciidoctor for structured authoring, plantuml and kroki for diagrams-as-code, and docToolchain (Docker wrapper + plugins) to import PowerPoints/Excel and export to Confluence. Describes IDE plugins, Docker deployment, and executing architecture rules with tools like jQAssistant so documentation is generated, reviewed, and automatically validated.
AI-written summary · about
chapters (10)
- 0:00Introduction and motivation
- 3:41Problems with documentation
- 9:38Maturity level 0: Traditional
- 13:12Level 1: Lightweight formats
- 20:32Level 2: Standard structures
- 28:15Level 3: Diagrams as code
- 34:48Level 4: Tool integration
- 39:35Level 5: Continuous improvement
- 43:00Level 6: Executable docs
- 45:46Recap and conclusion
related talks
46mBest Practices for Keeping Architecture Documentation Up to Date
25mDocumentation as Code, Where to Start?
44mPushing documentation (so it doesn't hurt anymore)
51mDocumentation as Code (Explained to My Father)
41mStop making fool of yourself about documentation
35mThe practical implementation of Documentation as Code
47mDocumentation as code (explained to my dad)
46mAsciidoctor: because writing docs does not have to suck