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.

Get Ganesh Ramasubramanian’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

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.