Documentation as-code

Earlier we hire a documentation/Technical writer and the documentation that he generates was always kept in a separate and secluded place. Nowadays, tech writers have been asked to maintain their documentation as markdown/asciidocs. Then asciidoctor came into automatically generate HTML5/DocBook/PDF documentation on the fly from these static asciidocs.

Then, the project lead “Dan Allen” of Asciidoctor started an open-source project called Antora.

Antora is a multi-repository documentation site generator for tech writers who love writing in AsciiDoc.

A Typical Antora documentation layout can be represented as:

• Antora provides a nice way to split the content from the actual stitching parts.
• The main stitching of all the documentation is done in the docs repository.
• The documentation UI layout can be stored in a separate repository docs-ui repository. You can start with the default sample docs-ui from Antora for this purpose.
• Then, the actual content repository can be there anywhere else. Antora at the build time can pickup these content distributed in multiple content repositories dynamically.
• Antora playbooks (there can be multiple playbooks as shown above), generates static HTML5 content.
• This generated HTML5 content can be zipped and deployed as a web app container. And here you go !!!
• The web app can be secured in any way to restrict the viewers.
• We can have multiple HTML5 web apps generated. For example external which is applicable only for Customers and Internal which is only necessary for your internal employees.
• The internal docs are quite important because when there are multiple engineering teams, there will always be API contracts/Module level documentation which needs clear understanding.
• The docs repository also can store its own content. For example, this is the place where one can store the release-notes and migration-notes.
• This way we generate and host the product documentation in a centralized place.
• The customers who are in older version, can see the new features based on release-notes and will come to you for their upgrade to the newer version. Earlier “Sales-Team” has to pitch-in and explain about the new upcoming features to sell the product. This is just like pro-active measure to sell the product.
• The developers and professional services team has to just create the ASCIIDOCs for their module. The Engineering Head need to do the release-notes and migration-notes at the end of each release. The Tech-writers just have to stitch together the asciidocs and validate the grammars and add additional documentation in asciidocs as necessary. Puff… The job is distributed.
• As the asciidocs are quite close to the source code, the developers will modify as and when the implementation is updated.
• Also the asciidocs could also be generated from the source code. For example, one can generate from Java source code using Reflections the documentation, Swagger API documentation etc.,
• We can also attach source code snippets as part of the asciidocs using tags.

Summary

• Keep AsciiDoc documentation as close to the source code.
• Developers & Engineering team update the technical documentation as and when the feature is implemented.
• Tech writers concentrate only on stitching the documents in a nice way.