Documentation as Code

Tom Johnson has written two interesting posts on his blog on the “Documentation as Code” concept:

Documentation as Code can be interpreted in a few ways. Tom describes it as being able to store the documentation with the code:

From a technical angle, Etter argues that one should embrace lightweight markup languages, use static site generators, and store content in version control repositories with engineering code.

An other interpretation associated with this is that documentation should be seen as a design problem; it should be seen as part of the product (and seen in a similar way to the software code), rather than an add-on. If the documentation is stored with the code, it can mean that the requirements for documentation can be more closely linked to the code. When a requirement for a new feature is raised, so can a requirement for the related documentation. It can also mean that content that’s embedded in the UI, presented as on-boarding screens or presented as online Help, can be considered as different potential solutions to each user need.

Documentation as Code is a topic we touch on in our advanced technical writing training course. It’s an approach that we may see growing in popularity.

3 Comments

Ruth

I don’t see how the storage location of documentation has any bearing on whether its considered part of the product.

“….documentation should be seen as a design problem; it should be seen as part of the product (and seen in a similar way to the software code), rather than an add-on” – I totally agree with this but it is perfectly achievable irrespective of where any source is stored.

“When a requirement for a new feature is raised, so can a requirement for the related documentation” – yup, you can do that too no matter where documentation is stored.

Or am I being too literal and the meaning is that documentation should be installed with the product rather than sourced with the code source?

Where I work we store doc and code source separately (and most people are happy with that) but we run our task lists as complete teams and every feature is required to have documentation tasks (and code review tasks and QA tasks etc). I absolutely consider my documentation source as code – its HTML and XML and JS – and my teams consider it as an integral part of the product. Of course embedded content such as GUI guidance and tooltips inevitably lives with the source code but its content is reviewed by documentation team members.

Documentation as Code – RHD Blog

[…] almost 14K useless results. You will find that there is not even an entry in the Wikipedia. The Cherryleaf.com blog includes a couple of interesting links and describes it as being able to store the […]

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.