Throughout this article I will try to expose my vision, I think shared by many, on an area that is so necessary in software development as it is abused by developers, such as project documentation.

By documentation I not only mean the typical user manual, always obsolete, but also I intend to cover all aspects related to documentation throughout the evolution of the project, from its conception to its deployment including the README, the architecture, the API, the guides, incidents, etc.

Forget docs? - Tweet from Kelsey Hightower

[TIP] - Real case
A recent example that shows the negligence of development professionals in this matter, as well as the possible economic consequences that it may entail, can be found in the Lawsuit recently filed by Hertz against a development giant such as Accenture. Without entering the «reported » low quality of the delivered software, one of the requirements was to provide guides in an interactive and easily updateable format (i.e. documentation) and what Accenture delivered was PDF documents. When Hertz warned them about this, Accenture asked hundreds of thousands of dollars to adapt them.

Embracing Agile

For a few years now, the process of building software has embraced agile methodology as well as continuous deployment practices, in such a way that the generated code is in production in the shortest possible time.

Some companies get up to hundreds or even thousands of deployments in production PER DAY. Obviously this is only possible if the entire process is automated in most of the production chain.

This pace of deployment, together with the ideas of the Agile Manifesto on "Code above documentation" have provided developers with the perfect excuse to put aside an aspect in the construction of the software that they have never liked, but that is necessary, such as the documentation of what we develop.

Thus it is very common, nowadays, to find projects where the documentation of a new functionality in the API does not correspond to the latest version deployed, user manuals with outdated screenshots, or architecture diagrams that do not correspond to reality.

In most cases poor quality documentation comes from, among other things, of:

• • In sprint planning, the task of documenting what has been done is at the end of the sprint (in the best of cases).
  • A development environment "away" from the documentation environment (Git vs Confluence repository, for example).
  • Low or non-existent automation in the generation of documents.
  • Lack of controls and review of what is written by the rest of the team.
  • Justify the work done by including screenshots or huge log captures (the infamous, «Documentation by weight»).

Situation around us

Countless are the projects where documentation is done using text editors (like MS Word, OpenOffice or Google Docs to give a few examples) with infinite options and highly specialized in presentation (WYSIWYG). Virtually all of them incorporate a change control system where you can see who changed what.

However the format generated by these programs is usually a binary, with the disadvantages of versioning it together with the code. Likewise, to avoid unwanted modifications, we never share the document itself but we convert it, almost always manually, to some other format such as PDF.

There are also others collaborative tools, like Confluence, which among many other functionalities have an area to create and maintain pages to create blogs and articles for example. Unfortunately this does not fix any of the above highlighted issues as pages are hosted in a proprietary repository and format, distancing the team with a non-integrated version control among other things.

Also comment on the case of some development with a public API (SOAP or REST for example), where all efforts, related to documentation, are focused on keeping the list of functions and parameters updated and for this they use tools such as swagger. In my opinion, they do not get much more than those developers who still use JavaDoc or similar.

Thus we come to have the following panorama:

• • The context switch (programming IDE vs word processor) is an effort that causes both aspects to be addressed as two separate tasks (first I program and after delivering I will document).
  • The tediousness of the process means that the documentation has to be updated manually, with the well-known risks of discrepancies between both systems and low quality of the documentation.
  • Group work is not promoted and synergies are not taken advantage of. Documenting is a job that is delegated to the newcomer so that "so he learns about the business."
  • In the end, we will have a «documentation by weight » where, to justify the work, for example complete log files, XML of hundreds of lines or screenshots are included.

Documentation by weight

If we pay a little attention, many of these situations can be associated with the well-known «Technical Debt", where the choice of a simple and hasty development causes us to incur additional costs when we want to address an improvement in the product.

Similarly, the choice of commonly used but not integrated tools in the project, as well as perform Manual tasks instead of looking for automations, it will generate a «Communicative Debt».

Doc-as-Code

"Doc-as-Code" It is a work proposal to build and maintain the documentation in the same way that we do with the software. "Doc-as-Code » goes further and tries to cover all kinds of documentation related to the project from the conception, architecture, requirements, design, test, user guides and even information about deployments.

In this line he proposes:

• • Text only. Avoid using text editors that do not handle plain text (Word, OpenOffice, etc.).
  • Versioning documents in a repository (Subversion, Git, Mercurial) along with the sources.
  • Use incident systems (Issue Trackers) so that anyone can contribute or improve it.
  • Apply Code Review techniques to give value and quality to each contribution.
  • Automate and integrate the generation of the same in the Pipeline of the product.

The benefits that this approximation provides are:

• • The variety of team members intended to write the documentation are more integrated.
  • There is a greater involvement of the developers (they usually write the first draft and see how it gets richer).
  • Increase in the quality of deliveries, by being able to block new functionalities that do not have the necessary documentation (which will incentivize developers to create at least that first draft if they do not want to see their functionality blocked).
  • Increase in the amount of type of documentation by being able to cover other phases (technical details in deployments such as IPs, DNS, server capacities, for example).
  • Multiple output formats starting from an input format.

This approach would not cease to be one more work proposal, if it were not for the fact that it has also promoted the creation of a valuable ecosystem of tools that solve various aspects of "Doc-as-Code". In a next installment on Continuous Documentation we will break down these tools that leave us without excuses. If you don't, it's because you don't want to.

Doc_as_code idratherbewriting

Where are we going with this strategy? - Conclusions

Almost whenever the task of improve and integrate documentation within the software building process, a natural rejection by the work team, by understanding that we will have to learn new tools and languages. And in my opinion, this approach is doomed to failure, as the task has to be tackled by the entire team as a whole.

Despite being a fundamental piece in any project, documentation has always been a "stone in the shoe", probably because we are not aware of our "communication debt" and we assume that it has to be that way.

However, with an approach towards «continuous documentation», making continuous improvements in each iteration, reorganizing the structure of the documents, including new sections and integrations, automating parts, etc ... we can achieve that the small changes that are made in the product are documented with a sustainable effort.

Ultimately our goal has to be let the team experience the pleasure of being able to communicate progress in your work in a comfortable and rewarding way. The prize is juicy enough to encourage you to reflect on it, really.

If you liked this first approach towards «continuous documentation», In the next installment I will also include the tools that support "Doc-as-Code" and a brilliant practical example with asciidoctor (Spoiler!).

Editor's note

This article is based on the papers on Doc-as-Code, courtesy of Jorge Aguilera, the best champion of Continuous Documentation that we know. Its dissemination work is tireless, both in videos and in face-to-face sessions and, especially, in its highly, highly recommended 'theme park: PuraVida Software'.

Thank you Jorge and don't stop the doc-party!