Managing Documentation as Code for Technical Writers (+ Tips for Beginners)

Many times, managing technical documentation traditionally, using Content Management Systems (CMS) and Help Authoring Tools (HATs), can feel like a never-ending game of catch-up.

It’s a blur trying to remember the last time I didn’t manage documentation as code. The technical writing world adapted quickly to the docs-as-code approach of managing documentation. Its efficiency as a collaborative way to handle docs made it top other options when it comes to documentation.

As technical writers, it’s on us to ensure the reliability of the processes we use for documentation to ensure true correctness and completeness.

What is doc-as-code?

The docs-as-code approach is a method used to manage documentation the same way software development is handled.

The software development lifecycle involves the use of:

• IDEs to write code,

• Version Control Systems to store and track changes,

• Automated testing practices to ensure correctness,

• Continuous integration and deployment to automatically build, test, and deploy code.

For technical writing, this would involve:

• Writing the documentation in a simple markup language (like Markdown, HTML, XML),

• Using version control (like Git) to store the code and track changes,

• Automated testing to lint and format the code for spellchecks, link validation, and language improvements,

• Continuous integration and deployment to build the code, run tests, and publish the documentation.

Managing docs-as-code as a technical writer

Since docs-as-code are created and maintained using the same processes and tools as software development, technical writers without a background in software development may find it challenging to manage documentation effectively using this approach. However, as a technical writer, you can enhance (or begin) your documentation skillset by doing the following:

1. Choosing the right Markup language

A Markup language (like a programming language) uses structured syntax to define how text should be formatted or displayed on a document or webpage. Some common markup languages for documentation include:

• Markdown

• HTML

• XML

• AsciiDoc

• reStructuredText

When choosing a markup language, it’s important to consider that your choice of language impacts the ease of writing, formatting, and maintaining your documentation. Markdown is widely used for its simplicity and compatibility with version control and HTML elements.

2. Learning to use Git

Git is a version control system that helps manage and track changes made to code, storing them in repositories. This allows us to easily review and revert changes over time.

Imagine you're writing an essay. You don't want to lose track of your changes, so you save different versions with different names. Git is like that, but for code (and documentation). It keeps track of all the changes made over time, allowing you to easily go back to previous versions if needed.

You need to familiarise yourself with Git and Github (or GitLab). Understand concepts like commits, branches, and pull requests—it’s the backbone of managing documentation as code.

3. Using Static Site Generators (SSGs)

These days, Static site generators (like Docusaurus, MkDocs, Jekyll, Gitbook, etc.) are commonly used because they convert markdown files into HTML, enabling easy preview and deployment of documentation as a website. As a technical writer, it’s important to get comfortable with any (or most) of these tools, because being able to work with (or at least figure out) different tools is a skill that can come to play at any time.

When choosing a SSG, there are a few things to consider:

1. Ease of use: Some SSGs, like MkDocs or Docusaurus, offer a straight-forward setup, while others, like Jekyll, may require a bit more configuration.

2. Supported formats: Check that the SSG supports the markup language you plan to use.

3. Customisation and theming: Some tools come with built-in themes (e.g., Docusaurus), while others require custom styling. When choosing your tool, consider how much resources you’re able to put into styling your documentation site.

4. Integration with Version Control: Nowadays, most SSGs integrate with Git and CI/CD tools for automated deployment. But, before you choose your tool, check that it allows for all your automation needs.

5. Community and support: A lot of these tools are open-source, and open-source tools with a strong community can mean better support, plugins, and long-term maintenance.

6. Hosting compatibility: If you plan to deploy on platforms like Github Pages, Netlify, or Vercel, ensure the SSG is compatible with your hosting choice.

4. Implementing automated testing practices

Your documentation workflow might be different from mine, but one thing we’ll have in common is the many, many reviews. Even after many reviews, there are things we still might not be able to catch.

When you manage docs-as-code, you’re able to automate review and testing practices like linting, link validation, spell checks, language improvements, etc. With tools such as Vale or MarkdownLint, you can maintain consistency by enforcing style rules and catching any missed grammar or spelling errors before publishing.

5. Configuring CI/CD pipelines

Continuous integration and continuous delivery practices enable you to automate most (or all) of the manual tasks needed to get new code from your commit to production, including building the site, tests, and deployments.

Tools like GitHub Actions, GitLab CI/CD, and Jenkins help automate testing, formatting checks, and deployments. When documentation is updated, these pipelines make sure it is built and published automatically.

6. Collaborating with developers

As a technical writer, you might have to work closely with engineers. Sometimes, documentation might be in the same repository as the code. In cases like this, you can foster collaboration and maintain accuracy by encouraging developers to review content for technical accuracy and provide feedback.

It’s important that you learn how to work within code repositories and development workflows. For instance, using pull requests (PRs) to propose and review documentation changes, providing clear commit messages to follow code review best practices, etc.

By working closely with developers, you can ensure that documentation remains an integral part of the development lifecycle.

7. Maintaining documentation quality

The quality of documentation you publish can be measured by a mix of things: usability, readability, consistency, accessibility, etc. To ensure that your documentation remains high-quality, you can:

1. Use style guides: To keep things consistent, you can adopt any industry standard documentation style guide (like Google Developer Documentation Style Guide, Microsoft Writing Style Guide, etc.) of your choice, create your own from scratch, or do a mix of both. It’s preferred to adopt a standard style and adjust to meet your needs. This helps you stay consistent in tone, formatting, and terminology across your documentation.

2. Write concisely: Avoid unnecessary complexity. The simpler, the better. Keep sentences short, use active voice, and break information into digestible sections. This can improve the readability and comprehensiveness of your documentation.

3. Use readable formatting: Always structure your content with the right elements. Use headings, bullet points, tables, code snippets, etc. when needed. This makes your documentation easier to scan and improves navigation.

4. Ensure accessibility: Your documentation should be accessible to all users, including those with disabilities. Use proper heading structures for screen readers, provide alternative text for images, ensure colour contrast meets accessibility standards, and avoid overly complex language where possible. You can use tools like WAVE, AccessibilityChecker, and Axe to test accessibility compliance.

• Keep docs updated: Documentation cannot be regarded as high-quality with redundant information. Review and update your documentation regularly to reflect product changes. Use version control, automated checks, and scheduled audits to ensure accuracy and prevent outdated information from misleading users.

Adopting a docs-as-code transforms technical documentation into a more collaborative, automated, and scalable process.

If you're new to managing documentation as code, start small—experiment with Git, try out a static site generator, and gradually integrate automation tools. Collaboration with developers and continuous learning will help you refine your workflow and improve documentation quality over time.

Embracing this approach not only improves efficiency but also makes sure documentation evolves alongside the product, making it a valuable resource for users and teams.