Docs-as-Code: Why documentation should be hosted online and released as part of the product
Ideally, technical documentation should be hosted online, rather than written in word processors and distributed in PDFs.
Why host documentation online?
A PDF needs to be actively shared and downloaded, after which, its contents are no longer under your control. PDFs get out-of-date. Outdated information can eventually become harmful.
Even if you regularly create updated PDFs, you then have an issue with version control. You can’t force people to delete their older versions. You can’t be sure that people have the most up-to-date version. The readers themselves might not be sure that they have the most up-to-date version, or which of their PDFs might be the correct one. And, the most recent PDF might be buried in an email thread somewhere.
As a technical writer working with PDFs, you have to wait until the next version to fix any documentation issues, whether those are small fixes, like typos, or a major oversight, like incorrect technical detail. Even if you ship your documentation with the product itself in a ReadMe file –– which you shouldn't –– you can’t fix any issues until the next release, and this might depend on convincing customers to upgrade.
Finally, working with PDFs means first working with a word processing tool, like Microsoft Word. That translates into a lot of time styling content as you write it, instead of fully focusing on the substance of your content.
Online documentation removes these issues.
What is "good" documentation?
Good technical documentation is clear and useful to the reader, aided with the use of a style guide, along with empathy for the intended audience.
Documentation works best when it:
Is version controlled
Is easy to keep up-to-date and to apply fixes
Is in sync with product releases
Has a low editing overhead
Removes the need for context-switching
Is easily viewable both online and offline
Empowers colleagues in different teams to collaborate and contribute
Documentation also benefits from an efficient and effective process for delivering the output. That’s what a Docs-as-Code approach offers.
You don’t have to adopt a Docs-as-Code approach to maintain online documentation. The approach just streamlines the processes involved and ensures that the product and its documentation are aligned.
Docs-as-Code allows you to output technical documentation alongside the products your content refers to. Using the Docs-as-Code approach, up-to-date documentation is part of your “Definition of Done”, and must be written before a product or feature can be released. Documentation becomes part of the product or feature, and so can’t be neglected.
Docs-as-Code also allows you to collaborate with others to keep the content up-to-date and to track changes to content with version control.
Great! But, what is Docs-as-Code?
Docs-as-Code is an approach to writing and publishing technical documentation using the same tools as Engineering. Docs-as-Code streamlines the maintenance of online documentation by managing content as code. Managing content as code means:
Storing documentation source files in a version control system, typically Git.
Building and publishing documentation with automatic validation and templating.
Implementing a review and approval process.
With a Docs-as-Code approach, information developers continuously develop the documentation that helps people use the product, just as Engineering continuously integrates, deploys, tests, and monitors their work. This means that the process for a technical writer is similar to that of a developer working on a software project, such as creating an app.
As a result, publishing is no longer a special or challenging event. Rather, the approach involves a simple and functional process in which you build the documentation and ensure that changes don’t introduce errors before pushing them to a live website.
Docs-as-Code doesn’t mean you have to use one test framework for checking both code and documentation. It’s common to have two separate, but parallel, test frameworks: one for checking code, and one for validating documentation.
How do I communicate the benefits of Docs-as-Code to others?
Using Engineering processes and tools to publish content allows technical writers to review and publish updates faster. It allows you to work on content without worrying about visual layout and style, since these aspects are already configured.
Docs-as-Code also empowers colleagues, especially the Engineers who build the product, to provide their own input. People are typically eager to share what they know when they get to talk about something they care about, so much so that many do it for free –– at work, in gaming, in open-source software projects, and in wikis.
Ideally, you still create the majority of technical documentation yourself as part of a Continuous Integration (CI) release process, or “continuous documentation”. Your job as a technical writer is also then about quality-control. Contributors don’t publish changes directly to a production website, but can suggest changes, which then pass through a review and approval process with a technical author.
In sum, the benefits of docs as code are as follows:
Efficiency, by publishing in alignment with Engineering working practices.
Accuracy (which also helps to establish trust) by making documentation easy to maintain and update.
Consistency, both in style and purpose.
Findability, by making content easy to tag, to include keywords for SEO, to access online, and to search.
Collaboration, by fostering communication and cooperation
Integration, by synchronising documentation release with the functionality of the product.