Product Spotlight: Andrew Owen on Docs as Code in a CCMS

In software documentation, a “docs as code” approach means that technical writers create all documentation using the same workflows and tools that software developers use. The idea is that this will increase efficiency and improve collaboration, but Andrew Owen, Solutions Engineer at Paligo, says that the approach is lacking in several important ways.

In his 15 years of experience as a technical writer, Andrew has worked in-depth with software development teams using a docs-as-code process. During one of these projects, he became an early Paligo customer. He says that his take on docs as code might not be popular with development teams, but he believes there is often a better way to work.

Andrew Owen: The docs-as-code philosophy is that technical writers will work like developers do, using the same developer tools and processes. This means that all documentation and code are saved in a Git repository, and both are created using a lightweight markup language like Markdown. The docs-as-code approach is supposed to improve collaboration between writers and developers and make it easier for developers to write first drafts.

Andrew: I was working as a technical writer when docs as code started to emerge, more than ten years ago. I think the main driving force behind it was that software teams started adopting Agile. They thought, now that we’re pushing code out every two weeks, how are we going to get the documentation out with the same cadence?

Up until that point, a lot of companies were still doing the waterfall model of software development, which probably had the highest cadence of a monthly release. With a waterfall process, you know in advance what you’re delivering, so you have something to hand to the documentation team at that step.

As soon as you go to Agile, however, you don’t necessarily know what is coming at the end of any release, because it can change during the development cycle. The old process of writing the documentation, doing a test publication, and sending the PDF out for review doesn’t fit very well into Agile. When you update with even more frequency, like with DevOps or CI/CD, where changes can be made every hour, then the traditional process doesn’t work.

So docs-as-code was created to help solve this documentation challenge. I think developers, product managers and engineers thought, we’ve adopted Git, we’ve adopted this kind of pipelining solution, and since both code and docs are text, writers can come use our tools and we’ll make it work.

Andrew: I think the fundamental flaw with the docs-as-code approach is the assumption that since docs are text and code is text, we can therefore use the same tools for both, when actually they each have their own specific requirements.

Seasoned technical writers are quite resistant to this approach because it means they have to go from using more sophisticated documentation tools to using simple markup language tools, some of which don’t even include a spellchecker.

Docs as code can also make publishing difficult, because the text doesn’t include any metadata. You can quickly get into a situation where headings are not lining up because the text is not XML-friendly. The outputs you can get out of it are also pretty basic. You might have a simple FOP (formatting objects processor) to generate PDFs, if you can generate them at all.

Andrew: The docs-as-code approach can involve sticking all your docs in a single Git repository, which is not a great way to work.

Let’s take the example of release management for a publication. When you do releases in Git, it includes the entire repository. So with docs as code, are you then going to have a different repository for each publication? And how are you going to navigate across those multiple repositories? This can be very hard to manage.

One of the biggest problems with the docs-as-code approach is that it doesn’t scale. I think docs as code probably works if you have one product, one writer, and two languages tops – it’s a very specific kind of situation. The moment your volume of content increases, or you add more writers working on the same content, or you need to reuse content or do more fine-grained versioning, or manage more translations, then you’re going to need a component content management system (CCMS).

Andrew: At the heart of the docs-as-code philosophy, there’s a good idea that you want your docs teams aligned with your engineering teams. It’s important in Agile, it’s probably more important in DevOps, and it’s absolutely critical in CI/CD, because if you’re putting out builds on an hourly basis, you’ve really got to handle that well.

Where I disagree with the docs-as-code idea is that to align with engineers you have to use their tools. If you use a CCMS, writers can use high-level documentation tools and leverage APIs to automate integrations and publishing.

In the Paligo CCMS, for example, a software build in your CI/CD pipeline would trigger an API call to Paligo, which would push out the work-in-progress version of the documentation to a staging site. By automating the integration, writers don’t have to use the coder’s tools.

The same is true for the documentation review process. If a pull request is made in Git, and you’re using Slack or Teams, you’ll get a notification in that channel. Because Paligo integrates with Slack and Teams, this improves the communication between writers and developers. It’s the spirit of collaboration behind docs as code, without following it to the letter.

Andrew: The immediate benefit for me, as a single author, was the taxonomies, which I hadn’t even been considering when I was looking for a documentation tool. With Paligo, I could create a taxonomy of functionality for the complete documentation. This meant that when I got a message from the developers saying that they had changed a piece of functionality, I could search by taxonomy and immediately have a list of everything I needed to check for updates.

The other benefits were Paligo’s automated layouts for PDFs and HTML publishing, and being able to easily manage multiple versions. Overall, it was a better user experience. With Paligo, you can restructure content with drag and drop, while if you’re using Markdown, it’s going to involve a lot of manual editing.

Andrew: My main role is talking to potential customers and trying to work out if Paligo is a good fit for their needs. I’ll demo the parts of the platform relevant to them, but also work with them on specific technical solutions, like the best way to migrate content from Confluence. Sometimes I get brought in when there’s a “docs as code” discussion, because I have this alternative view of how to do it.

Andrew: Because I was a Paligo customer before, I was already convinced of its usefulness. As a technical writer, Paligo exceeded my expectations and made my job so much easier. I previously worked with developer advocacy, and what I found out in that role is that you really have to believe in the product to do it. I genuinely believe Paligo is the best-in-class solution, period.

As a Solutions Engineer, I get to help people every day, which is one of my core values. My job never gets boring because every customer is different, and there’s always a new challenge to solve.