Show More
Menu
Image
Hi there! I am Federico Trotta

Technical WriterFreelance

Docs-as-code: Why You Should Treat Documentation as Code

Marzo 3, 2024
By Federico
0 Comments
Post Image

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.

Conclusions

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

However, to be able to do this, 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.


Hi, my name is Federico and I am a freelance Technical Writer:

Federico Trotta

Do you want to start a documentation project, collaborating with me? Contact me!

Do you want to know more about my work? You can start with my case studies and my portfolio.

Federico Trotta

Technical Writer: I document digital products and write articles about AI & Python programming.

Leave a reply