Documentation As Code

Often there are situations, where delivered artifacts and documents are not in sync. There is often some disconnect between the code/artifact developer and the document writer.

With docs-as-code, Documentation is treated in the same way as writing code.

• Use the same IDE to write it.
• Use the same version control system to store and version it.
• Document and source code/artifact reside in the same code repository.
• It makes it easier to manage different versions in a changing environment.
• The different team member can be responsible for their part of the documentation without any interference from others.
• It provides flexibility for different outputs (ex:html/pdf/..)
• It makes it easier to contribute back with different web-based blogging and knowledge base platforms.

There are many ways of implementing it. Some use markup language and some use Asciidoc. Here is my take on this topic.

Markup vs Asciidoc

The main advantage of Markdown lies in its primitive syntax. But this advantage is also its greatest weakness. When authors need something slightly more complex than basic prose (e.g., tables, cross references, footnotes, embedded YouTube videos, etc.), they find themselves resorting to embedded HTML or seeking more feature-rich implementations.

AsciiDoc presents a more sound alternative. The AsciiDoc syntax is more concise than (or at least as concise as) Markdown. At the same time, AsciiDoc offers power and flexibility without using HTML or “flavors” for essential syntaxes such as tables, description lists, admonitions (tips, notes, warnings, etc.), and tables of contents.

Engagement report: documentation-as-code

Here is my take on creating a consulting engagement report.

Get Shrishs’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

NOTE: I am using vscode with asciidoc plugin.

• Create a file with the .adoc extension. A complete template is mentioned and created here.
• Start with the title & different variables used in the document.

= {subject} - {customer}             
:subject: Engineering Labs - Platform Navigator 
:doctype: book
:confidentiality: Confidential
:customer: Customer XXX
:listing-caption: Listing
:toc:
:toclevels: 6
:pdf-page-size: A4
:pdf-style: engagement
:pdf-stylesdir: .
:numbered:
:title-page-background-image: image:img/title-background.png[position=center center]
:revnumber: 0.1

• Create a history and revision section to track different changes

== History and Revisions

[cols=4,cols="1,1,3,4",options=header]
|===
|Version
|Date
|Authors
|Changes


|0.1
|02-Jan-2024
|Author one <author1@xlab.com>
|Added Installation section.

|0.2
|19-Jan-2024
|Author two <author2@xlab.com>
|Incorporate review comment in Installation section.

|===

• Create subheadings like.

== Introduction

This enagement reprt describes my engadement i have done for the {customer} .

== Architecture Landscape

.Supervisor Cluster Networking
image::img/architecture.png[architecture.png]

== Installation
Following activities are carried out during installation.

=== Environment Validation

* Verification of management network in vSphere.
* Verification of NSX-T configuration

• Mention some issues you faced during the engagement.

==== Support Ticket created

* https://cert-manager.io/docs/[NSX MTU issue] 
* https://cert-manager.io/docs/[Harbor registry issue]

== Known bugs
* istio control plane only installs in istio-system namespace
https://github.com/istio/istio/issues/24037

• End it with the Appendix section.

== Appendix

=== Gateway Definition
[source,yaml]
apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: bookinfo-gateway
  namespace: bookinfo
spec:
  selector:
    istio: ingressgateway
  servers:
  - hosts:
    - productpage.bookinfo.uk
    port:
      name: http
      number: 80

      protocol: HTTP

• Preview the document created.

• Commit it to the GitHub repo. It appears as follows in the GitHub repo.

• A pdf can be creates using the following command

asciidoctor-pdf engagementreport-template.adoc

• It can be converted in HTML docs as follows.

asciidoctor engagementreport-template.adoc

• It can be converted into a .doc file. One needs to install Pandoc. Use the following command.

asciidoctor --backend docbook --out-file - engagementreport-template.adoc | pandoc --toc --toc-depth 5 -N --resource-path .:img --reference-doc=custom-reference.docx --from docbook --to docx --output "engagementreport-template".docx