Let's Treat Docs Like Code
We at tekom Magyarország started our local events for 2022 with a topic that has been in focus more and more in the last couple of years – creating documentation through collaborative writing. Like most group activities, collaborative writing has both benefits and pitfalls. But with the right approach and processes, we can open up a new world and tap into a pool of diverse experience, skills, and knowledge. However, if we want to encourage people to contribute to our docs, we must look at documentation from a different perspective.
What is docs-as-code?
To see a real-life example, we asked Diana Lakatos from platformOS to present for us the case study of their UKTC Award-winning developer portal. The platformOS team creates technical documentation with a collaborative approach. They want to provide consistent and high-quality content, make it easier to work closely with subject matter experts from their teams and community, and also support their agile delivery approach. To achieve this, they manage documentation in the same way developers manage code, known as the “docs-as-code” approach.
Diana showed us a complete docs-as-code workflow in her presentation. She started out by putting everything in context – introducing their team and community, and the documentation site itself. She also explained the main concepts of this approach and how they produce and manage content. In the theoretical overview, she walked us through what it means and why it is good to follow the docs-as-code approach.
The platformOS team writes content in plain text format using a text editor rather than a markup language like XML. They publish content with a static site generator instead of an expensive or bespoke publishing system. Behind the scenes, they manage all content via GitHub, which matches the way developers work with code, following a Git workflow. Much like the dev teams, they write, review, test, merge, build, deploy and iterate constantly for docs. They have also implemented workflows for contribution and editorial rounds. They track issues and review and edit contributions from their team and community. For consistency, they have developed a style guide and templates for all contributors. In her presentation, Diana also provided some details about how they built their continuous integration and continuous delivery (CI/CD) with GitHub Actions.
Why use docs-as-code?
It has been a common practice for technical writers to manage and publish large sets of documentation in complex content management systems. As we found out, this doesn’t really work for platformOS, as they are trying to deliver information to their users as quickly and easily as possible using the minimum content. They also need a publishing process that can support fast product evolution, continuous delivery, and collaboration between technical writers, subject matter experts, and users. For them, docs-as-code means flexibility and control. By working in the open, anyone can contribute to their documentation, and the whole team has shared ownership of the content. By using Git for version control and GitHub repositories to host their documentation, they can iterate docs alongside their product and make sure they stay in sync. platformOS documentation works with continuous integration and continuous deployment, and it automatically runs tests and deploys to staging and production.
At the end of her presentation, Diana hosted a Q&A session where attendees could ask her questions. It was great to see the interest raised and the questions coming in. We had a good discussion before closing the event.
We hope that sharing this use case benefited the attendees on their journey into the world of docs-as-code, or at least brought it a little closer into focus by explaining the basics and giving some insight. If you are interested and want to check out the documentation featured in the presentation, visit the platformOS doc site.