Technical writing and code, we've naively assumed, are two separate things. But effective agile software companies these days treat them as anything but.
From Microsoft to small startups, more companies are treating their technical documentation, technical docs, and technical content marketing assets much like they treat their software. This means everything is versioned, tested, and promoted to production, just like when releasing software.
Why go through this much hassle? Because the parallels between technical writing and code are too strong to ignore, and the peril of ignoring them is too great. In this article, I'll cover the basics of docs as code and share some experiences implementing it based on my work at Microsoft, Amazon, and ercule.
Why content as code isn't just a metaphor
Why treat technical writing as code? Many reasons in this day and age. A few of the top include:
Like code, technical content either works or it doesn't. Technical documentation is a living, breathing entity, just like code. The more technical the topic (like a walkthrough, or an article with a quick tutorial at the end), the more true this is. A piece of technical content that doesn't work for a user (e.g., a product walkthrough with missing or inaccurate steps) is just as broken as a server-side script that throws an HTTP 500 error.
Technical documentation decays. Also, like code, technical documents decay and grow more buggy over time. This can be either due to product or marketing drift. In the former case, your content gets outdated because your product's changed. In the latter, it's outdated because how you sell your product (the target audience, use cases, emphasized features) has shifted in response to market conditions.
Technical writing is increasingly wedded to code. XML, OpenAPI, Markdown, and other documentation formats mean that more technical writers are embedding their docs either alongside or directly in code assets. Thus, it makes sense to ship them as part of the same development process to ensure they're always intertwined and mutually updated.
Documentation increasingly is code. The corollary to this is that, because we wed technical writing to code, we're increasingly representing content itself in machine-processable formats, like Markdown or JSON. That makes it easier to parse as code and lint via automation.
Technical writing can be modularized. Reusable snippets, product names, feature names, boilerplate warnings, and other volatile elements can be factored out into substitution macros. This makes technical documentation easier to maintain in the long run.
Technical writing should be versionable. Who changed a given piece of content? When was it changed? Who approved its promotion to prod? Can we revert it if it's wrong? Most content management systems (CMS) don't handle collaboration well, if at all.
For years, software engineers have shipped changes using a Continuous Integration/Continuous Deployment (CI/CD) process. CI/CD makes sure everything is tracked, versioned, reviewed, tested, and re-tested before it makes its way to customers.
Technical writing can, and should, follow the same pattern. Too many teams, however, are still Wild West-ing their technical documentation, pushing Publish the moment it clears spell check. The result is that most errors get fixed after the fact (if at all). Over time, content grows stale and stops working until, eventually, customers lose trust in what you've published.
Treating technical writing as code is part of an effective content maintenance strategy. Having an automated system to assist in publication means you have a concrete process for quickly identifying issues, checking in and reviewing changes, and publishing fixes in a timely manner.
Docs as code basics
How do you get started with docs as code? Let's start by addressing the basics you need to have a solid technical writing workflow in place.
I won't get into how to implement such a system here. There are some commercial solutions that can get you started. Your software development team can also assist you in setting up a basic process using freely available or affordable tools, like Git, GitHub, and Jinja.
Put everything in version control
The fundamental starting point for docs as code, or any CI/CD automation, is getting everything under version control. This requires two things:
- Using a version control system such as Git or GitHub; and
- Representing your technical documentation in a plain text format like JSON or Markdown
By putting everything under version control, you can tell who changed what and when. If two technical writers submit conflicting changes, the system catches that and asks them to resolve the differences. You can also revert changes, e.g., if you discover a flaw that requires more investigation before correcting or if you have to pull a new feature back.
From an automation perspective, a version control system also gives you an event to drive automated review and publication. Whenever a change is submitted, the version control system can track this and initiate the workflow that will eventually end in new technical content being automatically published to your website.
At most companies, writing documentation is still a highly manual process that's prone to error. Version control and CI/CD turn it into an automatic, repeatable process with built-in safeguards.
Use pull requests for automated and manual reviews
In a CI/CD system, everything revolves around the pull request.
This may sound like an overly complicated concept. But in practice, it's pretty simple.
In your version control system, all of your technical documentation is in a repository (repo). There's one repository, usually called main, that represents everything you've approved for publication.
When a technical writer makes a change or submits a new document, they don't put it in main. Instead, they create their own copy of main, called a fork, and make the change there (called a check-in). This prevents anything that's still a work in progress from being published inadvertently.
When the tech writer is finished making the change, they file a pull request, or PR. The PR is a technical way of saying, "This document is ready to ship to production, please start the review process."
Every PR has two quality elements: manual and automated.
From the manual side, every PR must be approved by at least one other team member. This human-in-the-loop element ensures that all changes receive a second set of eyes from team veterans, who can easily spot common mistakes.
Pull requests can also contain automated checks. For example, when a PR is created, you can configure your pull request to run a series of automated checks: spelling/grammar check, brand guidelines check, code sample checks, etc. These can be spit out as warnings or even as blocking errors that require resolution before the PR can be approved.
This example from GitHub demonstrates using a spell checker to catch errors in a Markdown file.
Build everything automatically after PR approval
Once a pull request is approved, this triggers a set of automated processes that push your technical documentation to production. If the content is a single blog post, this might mean triggering a rebuild to push the new content to your website, either via a static site builder or using the API for a CMS system like WordPress.
You and your engineering team can build this system from scratch if you’re so motivated. Most companies will find it easier to use a docs-as-code platform such as ReadTheDocs or Docusaurus.
Building a more complex CI/CD docs system
The beauty of using a CI/CD workflow is that you can handle all kinds of complicated technical documentation. The more complicated and multifaceted, in fact, the more value you gain from using a CI/CD content publication system.
Let me give an example. At AWS Training & Certification, we published materials for three-day courses to train software engineers and system administrators worldwide on how to use Amazon Web Services' cloud services. This consisted of:
- A copy of the instructor's slides, with DRM attached to protect AWS IP
- A set of hands-on labs available during class, with lab instructions written in Markdown and AsciiDoc
- A PDF of the lab content for future reference, so that students can perform labs at home
When I arrived at AWS, we built all of this manually for the dozen+ courses we ran (and counting). It took one to two weeks and a ton of manual labor to ship a change. That meant that we...didn't make them! Our courses would accumulate bugs until we got around to fixing them once every three months (or less).
A year after I arrived, a colleague and I decided to fix this. We wrote an automated system in Jenkins that rebuilt and re-published all of our course materials, using our lab vendors' APIs and tools such as Pandoc and ActivePDF to assemble course materials.
As a result, curriculum developers fixed bugs and shipped new releases weekly. I left AWS in 2020, but last I heard, this system was still going strong.
Monitor technical writing in production
One challenge in the cloud/Software as a Service (SaaS) world is that everything is constantly changing. Development teams ship changes weekly. Some release daily. Often, technical writers are the last to hear about these changes.
This makes it imperative to monitor your technical documentation after it's released. This can take one of several forms depending on how much content you have and of what type:
- Attach feedback forms to technical content for reporting issues
- Create a forum for discussing documentation or reporting bugs
- Identify your top technical writing using metrics and review/test it periodically (e.g., monthly) to ensure it's in top working condition
A tool like the ercule app makes it easy to identify your top-performing technical content without needing to become a GA4 expert.
Conclusion
An automated publishing system isn't enough to create great technical documentation. You also need to create a data-driven technical content strategy and create a process for managing your technical content pipeline.
Treating your technical writing as code, however, makes publishing technical documentation easier. It reduces the barriers to shipping changes so that you can keep your most important technical documents in pristine working condition.
