Contents
When our company decided to migrate from Confluence to a new documentation platform, our technical writing team faced a choice: follow others to a new platform or rethink how documentation is stored and move it to live alongside the product itself. We chose the second option and transitioned our documentation to a docs-as-code approach, maintaining it in a repository close to the source code.
We aimed to bring documentation closer to development workflows so that changes could be reviewed alongside code. With the docs-as-code approach, automation became easier to introduce, and long-term scalability and versioning felt more robust. As an accidental bonus, this approach also laid the foundation for future automation and AI-assisted workflows.
However, the transition came with high costs and hidden issues. Both non-technical and technical contributors faced difficulties, and the learning curve turned out to be steeper than expected. The process itself became more complex, required additional tools and guidelines, and overloaded the team, which eventually became a bottleneck.
Takeaways
This talk presents a case study of our transition from a wiki-style platform to a docs-as-code approach, highlighting the benefits, the challenges we faced along the way, and what we would do differently if we could start over.
Prior knowledge
docs-as-code