When starting a documentation implementation strategy for software, one of the methodologies you can choose is the so-called “docs-as-code” philosophy which means treating documentation as if it were code.

This article describes the characteristics of the doc-as-code methodology, and why use it.

Features of the docs-as-code methodology

Applying the docs-as-code methodology and treating documentation like code means using typical development methods such as:

  • Use of Git. In particular, GitHub for:
    • Documentation versioning.
    • Collaborative review via Pull Requests and related conversations.
    • Deploy using automation.
    • testing of the documentation.
  • Use of Markdown.
  • Max personalization.
  • Static pages deploy via services like GitHub pages or Jekyll.
  • Possibility to make users interact with the documentation, opening Pull Requests to improve documentation quality.

When to implement the docs-as-code methodology for your documentation

When starting a document project from scratch, the design part is very important.

In general, it is always good practice to be able to create documentation following the docs-as-code methodology, but you should take into consideration the environment in which it is implemented, and the relevant stakeholders.

In fact, not all stakeholders who interact with the documentation have the same knowledge and skills as the developers. Sometimes, the person reviewing the documentation may be a person who works in marketing rather than a project manager. These figures may not be familiar with the use of Git and related tools.

So, in general, this methodology can be implemented when working in corporate environments where stakeholders:

  • They are all developers.
  • They are not all developers, but they are familiar with typical development methodologies.

Of course, the choice also depends on the type of company. In general, it is likely that in a start-up all stakeholders are familiar with the typical development methodologies. Less, in a large company.

In any case, when designing the documentation, this is the first thing that has to be decided. This is done by establishing who will interact with the documentation, including reviewers.

Why implement this documentation management methodology

Implementing this documentation management methodology guarantees:

  • Maximum flexibility in the implementation of the available templates, to have a tailor-made front-end.
  • Speed ​​of execution and deployment into production, as these are static sites.
  • Ability to functionally test the documentation and view it in a staging environment, to avoid errors before the deployment phase in production.
  • A highly collaborative environment.

Conclusion

Whenever possible, choosing to develop documentation following the doc-as-code methodology is preferable.

However, the stakeholders involved in documentation management must be familiar with typical development methodologies.

In the design phase, once the stakeholders have been defined, it is established whether this methodology is applicable to your company or not.