Docs-as-code: Democratize your content

Getting technical communication resources is always a challenge and rarely scalable. There are always far more developers than there are writers. What if you could get your developers to write the content for you, creating a new, editorial role for your team? Why not get your developers in on the booming business of content?

Democratizing your content is the goal of docs-as-code, where your documentation files live in the same ecosystem as your developers’ code, using a format that is easy for them to learn and implement. Your content is version-controlled, easily interpreted, and scalable. Your docs team is responsible for setting up the framework, guidance, and enforcing the rules.

How does it work?

Docs-as-code files are unstructured and designed to be human-readable. The content is freeform with minimal formatting — for example, asterisks for bullets, combinations of asterisks for bold and italics, and heading denotation using hashtags (#). Consider them a polar opposite of a structured language like DITA.

The most popular language is Markdown (this blog post was written in Markdown); there are other languages, but they add complexity and domain knowledge. The beauty of these languages is that they’re interpretable by literally any code editor, so no matter which tools your developers use they can create content. There are also innumerable systems that transform this content into end-user content; even version control systems like GitHub and GitLab convert Markdown content into HTML pages.

Workflow

Your docs team becomes editors instead of writers. In a typical scenario, developers create their content and commit their edits to a version control repository. It’s reviewed by writers in a merge request or a pull request, which is a review step before merging to the main, or production, branch. Writers then make edits, ensure it conforms to the style guide and has a consistent information architecture, then merge to the main branch of the repository. The content is picked up by a static site generator (SSG) or a content management system (CMS) where it’s displayed to readers.

Adjustments for writing teams

Unstructured languages are easy to learn and use, but there’s an adjustment for writers used to a GUI or a structured language like DITA. If you’re used to a DITA environment, you lose things like content reuse, so consider your use case before making this move. You’ll also have to use the tools that developers your use to write, edit, and version control. The good news is these tools are highly used, highly customizble, and highly documented.

You have to give up some measure of control as you’ll have multiple developers creating content. Regular content audits will help you manage this. You’ll also play the role of educator to ensure people know how to use the language you choose and follow your standards.

Automation

To help maintain quality, you can automate your style guide using a linter. There are at least two open-source projects out there that contain various language rules, but you (and your developers) can create additional rules to ensure things like business-specific language or the Oxford comma are used. You can also implement a spell checker on your developers’ repositories to do a lot of heavy lifting for your team.

New opportunities

Changing your process is never easy or taken lightly, but if things aren’t working the way they are, perhaps it’s time to take a fresh look. Your readers are desperate for quality content, maybe a democratic approach to content will help you help them and achieve your business goals.

Leave a Reply