As I already advanced in the first part of my approach to Continuous Documentation, almost whenever the task of improving and integrating the documentation is approached within the software construction process, there is a natural rejection by the work team, by understanding that they 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.

If you have school-age children, this music may sound like… «The Traveler Book is a book that is born itinerant and that it is being written thanks to the collaboration of the different families to which it is arriving in its tireless journey ». It works.

The traveling book

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, guides, incidents etc. So "Doc-as-Code", as a work proposal to build and maintain documentation in the same way as we do with software, has promoted the creation of a valuable ecosystem of tools that solve various aspects of continuous documentation. 

I am going to break down in this second part of the article these tools that leave us without excuses. If you don't, it's because you don't want to.

Tools

I have pointed out that «Doc-as-Code » It is still a work proposal and on it, or at the same time, tools have been created that solve one or more aspects of it that can help us in the implementation of a ongoing documentation. For example:

• • Markdown is a light markup language with implementations in a multitude of languages ​​(perl, python, java, java, ruby ​​among many others), which allows the generation of visually attractive documents starting from text files. As a main problem, it should be noted that since it was not established as a standard, there are many different variants.
  • reStructuredText Like the previous one, it is another markup language, but more defined and complete. Although it can be used in other environments, it is used mainly in Python.
  • asciidoc is another markup language similar to the previous ones with a clear syntax and semantics-oriented. Asciidoctor It is the main implementation, developed in Ruby, although it is also found for Javascript or Java, and as a plugin for Maven and Gradle projects.

Recover the illusion of documenting your project with «Asciidoctor for Dev (Ops)

• • antora is developed by the same community as Asciidoctor and based on it, it allows us group different repositories with different branches, even in the same repository, generating a "Static site" with all of them integrated. Thus we can distribute the set of all documentation among different projects, teams and code branches while generating a version with all of them.
  • Spring Rest Docs This Spring project is a good example of how to make a product's Rest API and documentation "go hand in hand", so that if our documentation indicates that a end point it will need X parameters and it will receive Y, when the tests are executed, this check will be carried out (at the same time as the request and response are documented), failing the test if it is not fulfilled.
  • Geb It is an ideal project to be used in browser tests in such a way that we will programmatically navigate through the application to be tested, being able to fill in forms or check conditions on visual elements, with the addition that we can make automatic captures (screenshots) that may be attached to our documentation.
  • Static blog generators like jbake, Hugo, Jekyll can be used to create a knowledge base site, or tips on how to build our products, a welcome for the newly incorporated or any other space that we want to transmit.
  • Arc42 is a set of templates (Creative Commons Sharealike) to describe a software architecture. In this line it tries on the one hand, to provide a list of documents necessary to describe an architecture, and on the other hand it provides how to do it. Thus, they cover up to 12 points that every project should consider, such as: Definition of the objective, Stackeholders and requirements, Strategy, Static decomposition of the system, Deployment, Quality, and Risks.
  • docToolChain is an implementation of the vision «doc-as-code » It offers a set of tasks designed to integrate with different systems (Jira, Git, Sparx EA, Visio, Office among others) to produce an ordered set of documents. In addition to being able to be executed individually, it can be integrated for example in a Gradle project and be part of the pipeline in a natural way.

Starting from these tools is very easy, as shown by the large number of examples and tutorials that exist, create our own integrations with the systems we work with (as long as said system is not completely closed, which should ask us if it would not be better to migrate to another).

asciidoctor-to-markdown

So we can find or develop integrations such that:

• • Extract specific paragraphs from a Word file and dump it to Asciidoctor.
  • Retrieve the Jiras open in a project and integrate them into our documentation in each build, in the form of a table, listed.
  • Link paragraphs of the documentation by linking to a discussion in Confluence.

Continuous documentation integration DocToolChain

Towards continuous documentation

The task of improving and integrating documentation within the software construction process, must iInvolve all team members of the project. In most cases documentation is expected to be performed by technicians not directly related to the software (which, for example, do not use the version repository or are not part of the workflow directly) and who are asked to automate the more components the better (requirements, screenshots or deployments for example) .

A proposal for an approach towards a "Continuous documentation" should go through:

• • Ensure that all team members count with access to the repository, and who have the knowledge to perform the typical actions such as commits, reviews or merges.
  • Create minimal integration that generates a «index" and a " »And promote that it be edited and reviewed by as many team members as possible (both at the source and the final result).
  • Practiceuntil you have a basic understanding of the basic syntax and see that no special editors are needed.
  • Involve developers in tool integration such as those commented, which best fit the project, in such a way that the documents are enriched. Here for example they can work to include test outputs or to capture screenshots and link them in the correct document.
  • Promote the "Pair documenting" where two team members work on the same document at the same time.
  • Just as the code is organized in multiple files (classes, libraries, packages) documentation must be organized in the same way in multiple documents (index, chapter, tips, glossary) thus obtaining the same benefits as with the code (better understanding, reuse, avoid conflicts).

Practical example with Asciidoctor

As an example I will describe a hypothetical case where to apply the concepts seen:

At one point someone has a happy idea about a new project or a new one feature to incorporate an existing one, and create in a new repository the slides of a presentation where the idea is explained. To do this, DO NOT use PowerPoint or similar, but create a plain text file and using "Asciidoctor-revealjs" you can convert it to an HTML presentation that is updated every c (delivery).

[TIP] When using plain text you focus on the content and not the presentation. It also facilitates the review by other members and the presentation is kept up to date with each change.

Once the idea is presented and approved, work begins on it. Software architects will be able to express their vision through diagrams "UML" using, for example, the plugin "PlantUML" which, starting from a plain text, is capable of generating the corresponding image.

[WARNING] Probably this proposal falls short for an architect because his work tool will surely offer him more functionalities. The important thing is that it allows you to extract that design in some way, either to a text file or to an image in an automated way.

As developers progress through implementation, they will be able to link part of their code to documentation with a simple "Include: myfile.java [tag = method]", preventing it from becoming outdated due to changes in the code, while offering you a visible place where you can explain the implemented functionality.

[NOTE] Little by little, the developers see that this approach allows them to better express their work than in the typical javadoc, in addition to gaining visibility.

Likewise, integration test They will be able to check that the API is in line with the documentation and they will generate screenshots that can be included in the user manual (for example) by using "Image :: screenshot.png []". With a little script the team will have a updated and integrated document with the rest of the documentation of the Issues open.

[TIP] If for example we use Jira we can make inquiries Rest that they give us back the issues of our interest, dump them to a table in a file «Issues.adoc»And include this script in our pipeline.

Through a simple integration with the repository, at the end of a product version, we can automatically generate a file "CHANGELOG" that shows the changes made between versions (using the commits o Pull request performed).

[TIP] There are many plugins, depending on our work environment, that allow us to interact with the repository Go and thus be able to generate a list of changes that we will dump to a «CHANGELOG» file. In the worst case, when we cannot find a plugin to our liking, we can use our own Go running "Git log" and extracting the changes of our interest.

Doc_as_code idratherbewriting

Conclusions

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 it has to be.

However, with an approximation towards the "Continuous documentation", making continuous improvements in each iteration, reorganizing the structure of the documents, including new sections and integrations, automating parts, etc ... we can ensure 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 (again) encourage you to reflect on it, really.

I remind you that in the first part of my approach to Continuous Documentation we establish its bases. If you liked this approach to "Continuous Documentation" I will be happy to comment with you on the various approaches we can take in our implementations.

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!

PuraVida Software logo