As the leader of the Arundo documentation team, I was recently given the challenge of developing a publishing process that enables people across our company to contribute to docs. I was also required to keep costs down and use as many of our existing tools as possible. This was an exciting challenge and one that we solved by switching to a Docs as Code philosophy.
What is Docs as Code?
Docs as Code is all about writing and publishing documentation with the same tools that developers use to build software. Content is written in markdown using a text editor and then stored in a repository where it can be reviewed by peers. Once approved, the content is built into a website using a static site generator and deployed to a web host by an automated process.
Implementing Docs as Code
All of this sounded fantastic to me and after researching some of the tools necessary to implement Docs as Code, I knew that we could leverage our existing GitHub project to store content and handle reviews.
I then found a perfect theme for us to use for our docs, MkDocs-Material, which uses Google’s Material Design approach, the same philosophy we use for our apps. Here’s an example of the theme used on our Arundo Edge Help Center:
An added bonus was that this theme is designed for use with the MkDocs static site generator, which is a very fast and easy-to-use.
Excited at all of the momentum, I met with our DevOps team and found that we could use Travis CI to set up automation to deploy content from GitHub to Kubernetes. From there we could make our docs available on the web and accessible to everyone or restricted to certain users.
So as you can see, we were able to solve our challenge by leveraging a lot of the tools and expertise we currently had available. Docs as Code has worked brilliantly for us and continues to provide the following important benefits:
- Reduced costs - We were already using GitHub, Travis CI, and Kubernetes so we didn’t have to pay any extra to use these tools for our docs. Plus, our doc theme was downloaded for free and the MkDocs static site generator also costs nothing to run. The only real cost was some time to up my skills but that didn’t take long and I became an expert pretty quickly working with Docs as Code on a daily basis.
- Increased collaboration - We now have people in all departments across the world contributing to our docs. Within a few minutes, anyone can get up and running on a doc project. We are also able to track content updates and handle doc reviews seamlessly through pull requests, saving the need to use any third-party tools for reviewing.
- Seamless publishing workflow - We can merge content updates and through the power of automation, have them deployed to the web in minutes with no manual steps necessary. Writers don’t need to be DevOps engineers to push out updates but DevOps engineers can be writers if they want!
- Flexibility - Our doc theme is open-source and highly customizable, so I can update the theme myself to meet our needs. I can make most of the necessary customizations myself but if I get stuck, I know I can bend the ear of a friendly developer to help me out.
Docs as Code has been a game changer for us and revolutionized the way we produce documentation by making things easier. Instead of writing everything myself, I now have people from across the company willing to step in and write content, and reviewing content updates is quick and easy.
If you are curious but hesitant about using the Docs as Code approach, give it a shot. You will be amazed at what it can do for you and your team.