Lessons Learned: arc42 in a Real Devops Team
summary
A corporate DevOps product team moves unstructured docs into arc42 in a wiki, then switches to Docs-as-Code with AsciiDoc and a repo-driven microsite; the result is searchable, versioned architecture pages integrated into Kanban work items and faster onboarding (from ~2 weeks to under one). Tooling and modular repos improve QA and review cycles, while persistent failures include mixing business and technical content, poor initial QA, and ugly PDF exports that force a shift to content-as-code and site rendering.
AI-written summary · about
chapters (11)
- 0:00arc42 in DevOps
- 6:09Documentation challenges
- 10:13Why architect docs matter
- 13:58arc42 template key elements
- 18:03Tutorials vs technical docs
- 22:23Text-only docs problems
- 25:10Code repos for docs
- 28:43Team docs structure
- 33:37arc42 lessons learned
- 36:13Architecture decisions tracking
- 38:52Long-term doc benefits
related talks
46mLessons Learned: arc42 in a DevOps Team
42mLessons Learned Using arc42 in a Real DevOps Team
44mPushing documentation (so it doesn't hurt anymore)
45mDocs as Code Fix a poor documentation culture in your organization
47mEngineering Documentation
36mAgile documentation: A first class citizen
47mDocumentation Is Fine, Don't Worry
39mThe Documentation Dream: One Team, No Silos, Shared Goal