Documentation (especially developer documentation) flourishes when people (especially developers) outside the tech writing team can easily review or contribute to it. This is because tech writers cannot know everything worth knowing about an application, SDK, or API.
Traditional web publishing involves using CMSs ( content management systems) or HATs (help authoring tools) like WordPress. The problem is that when such tools are used to manage and publish documentation, it's difficult for people outside the tech writing team to contribute because of the limited access and authentication hurdles of the admin portal of such tools.
This need for an easier way to foster collaboration and contribution to documentation projects gave rise to the docs-as-code approach.
In this article, I'll briefly go over what docs-as-code is, when to adopt it, its benefits, and the tools you need to set up a docs-as-code pipeline.
What is Docs as Code?
Docs as Code refers to writing, publishing, and managing docs using the same tools and workflows developers use to write and publish code. Developers have already hacked code contribution and collaboration using tools like git and GitHub, and also automation with CI/CD pipelines.
By adopting docs-as-code, documentation teams can leverage the same ease of collaboration and automation that developers implement for source code.
When to adopt Docs as Code?
The question of when to adopt docs as code is best answered by a question I was asked by a Google Season of Docs (GSOD) intern.
She asked (and I paraphrase): "My fellow interns and I are working on a documentation project. How can we set up our documentation project such that by the end of the GSOD internship, if people stumble on a fix, they can contribute via Github pull request, and once it is merged, it will be automatically published in the docs?".
If you find yourself with a similar need, then you need to adopt a docs-as-code approach. As the open-source developer community has taught us, developers are more than happy to contribute to projects they like or use.
Benefits of docs as code
The primary benefit of the docs-as-code approach is that it fosters easier collaboration, as it brings your documentation closer to developers and the public.
If you're working on developer docs and require developers to either write the initial docs or review them, using tooling and familiar processes empowers them to contribute and participate more fully with the documentation authoring and publishing.
Other benefits of the docs as code approach include:
Automation:
With the docs-as-code workflow, you can leverage automation usually implemented for code.
For example, you can create automated checks to run at every pull request to detect things like technical errors (i.e., invalid links, invalid code snippets, etc.) or language errors (i.e., typos, missing punctuation, etc.) using natural/human language linters such as writegood, vale, or htmlSanityCheck.
If the tests fail, the contributor is notified to rectify the errors. If the tests pass, a member of the tech writing team can manually review and merge. Then, once a change is merged to the main branch, the docs site gets updated with the pull request changes. This way, quality is still maintained even though everyone can contribute to the docs.
Customizations:
As long as you, the technical writer, is familiar with programming or has a developer willing to help out, the docs-as-code route allows one to customize their workflow as they deem fit for lesser costs. If you can think and code it, you can have it.
Transparency and easier tracking:
Thanks to the versioning feature of git and the issue feature of code repository tools like GitHub and GitLab, one can easily track progress and every change made to the documentation. That way, in the event of an error, it's easy to roll back.
Components of a Docs as Code setup
To set up docs-as-code, you need 4 primary components: version control (git and a web-based git platform like GitHub, GitLab, Bitbucket), a static site generator, a CI/CD pipeline, and a web hosting platform.
Git:
Using git and a web-based git platform like GitHub to manage the content of a documentation site facilitates the ease of collaboration that is a core benefit of the docs-as-code approach. It allows for offline and concurrent work on the same file from different people.
When choosing what git platform to go for, go for what developers in your company are already using.
Static site generators:
Static site generators (SSGs) are programs that take content and themes (templated HTML and CSS), process them, and output a folder full of all the resultant pages and assets.
The appeal of SSGs is that, unlike with traditional web application stack, layout code is decoupled from the content in the form of themes. Also, the content is usually written with plain markup languages like Markdown or reStructuredText. This makes it easier for anyone to contribute as they only have to worry about the accuracy of the content and not how it will look.
The second appeal of SSGs is that, unlike traditional web application stack, which waits until a page is requested before it generates it, SSGs build all the individual pages ahead of time, so response times are faster. And, fast page load times mean better documentation experience.
Also, since SSGs usually process and output everything as simple HTML pages, hosting static websites is simpler. You can host static websites practically anywhere with the simplest web servers like Amazon S3 or GitHub Pages. My favourite web hosting platform is Netlify because of its inbuilt automation features.
In choosing which SSG to use, consider what languages and frameworks your development team already uses, so nobody has to learn a whole new language. For example, if your development team primarily leans towards JavaScript, you should consider JavaScript-based SSGs and themes. Also, consider what features you need for your documentation site. Some static site generators are explicitly built for blog pages, while others are specially built for the needs of documentation sites.
Examples of SSGs to choose from are SlateDocs (for API Documentation), MkDocs, Docsify, Sphinx, Docsarus, Gitbook, etc. Check out the staticgen website for other SSGs that you can use.
CI/CD pipeline or workflow:
A CI/CD (continuous integration and continuous delivery) is what affords us the automation that is a core benefit of docs as code. With a CI/CD workflow, you can write event-driven scripts to run automatic validation checks and deployment of your documentation site, as discussed above. Check this article to learn how to automate your documentation workflow with Vale and GitHub Actions.
Web hosting platform:
There isn't much to discuss in terms of web hosting platforms. As mentioned, because of the simplified output of SSGs, you can host them anywhere.