Some weeks ago, I joined an exciting new project at my company, where dozens of development teams and stakeholders collaborate to leverage AIOps, DevOps and ValueOps data to help our customers make better business decisions.

In this project, I’m responsible for the end-user documentation and also for designing a content solution to create a single (and consistent) deliverable for the project’s internal documentation (i.e. the documentation created by the teams that is not exposed to customers but might need to be shared with third-parties).

Streamlining internal documentation is always a big challenge, because this information is usually stored in different formats, on different platforms and sometimes even in different languages. Finding one size that fits all is not an easy task. Actually. it’s quite challenging…but with a bit of creativity and imagination it is an achievable goal (and a rewarding one).

In this post I want to share which approaches and tools you can use to:

• Select a format to be used by your dev teams that follows the docs-as-code principle, is dev-friendly and can live with the code.
• Convert existing documentation created in a variety of formats to AsciiDoc (you got it, this is the format I chose for several reasons, I explain it below)
• Use Antora to pull content from different repositories and even branches
• Include REST API content in your output

Challenge 1: Format

Select a format to be used by your dev teams that:

• Follows the docs-as-code principle
• Is dev-friendly
• Can live with the code

As a technical writer, I always follow the principle: “when in Rom, do as the Romans do”. That means, if you are organizing internal documentation to be maintained by developers, don’t try to reinvent the wheel. Refrain from using a documentation tool or CMS, stick with a Markup language. Why? Because it’s easy to learn and maintain and can live with the source code.

But which markup language is best?

To select the optimal format to be used for this project, I drew up a shortlist of possible options from the markup family that are commonly used, easy to learn and support xrefs and other necessary functions to create good documentation. The languages I chose to carry out a deeper analysis of strengths and weaknesses were: AsciiDoc and Markdown.

I finally chose AsciiDoc for the following reasons:

Note: Some of the reasons come from Eric Holscher’s post on this topic.

• AsciiDoc belongs to the family of lightweight markup languages, the most renowned of which is Markdown. AsciiDoc stands out from this group because it supports all the structural elements necessary for drafting technical manuals. In fact, it’s capable of meeting even the most advanced publishing requirements and technical semantics.
• Unlike Markdown, AsciiDoc does not require the use of HTML or “flavors” for essential syntax such as tables, description lists, admonitions (tips, notes, warnings, etc.) and table of contents. AsciiDoc uses a consistent formatting scheme (i.e., it has consistent patterns).
• Markdown lacks semantic meaning (no admonitions supported): Though many people have added extensions to Markdown, almost none have any kind of semantic meaning. This means that you can’t write a Class or a Warning, you can only write text. This leads people to embed HTML directly in their Markdown.
• Markdown cannot be migrated easily. You also can’t migrate Markdown easily to another markup language (Asciidoc or RST), because Pandoc and other conversion tools won’t support your flavor’s extensions. A lot of people choose Markdown because they think they can migrate to another tool or markup later. Markdown is definitely the lowest common denominator, except that for any reasonably sized set of docs you’ll need things that aren’t in the basic language.

Challenge 2: Conversion

Convert existing documentation created in a variety of formats to AsciiDoc.

This part was tricky, but also fun. The good news is that there is always a way (or a workaround) to convert content to AsciiDoc.

I used PanDoc for converting existing Markdown content into AsciiDoc. PanDoc is a universal document converter for markup languages: https://pandoc.org/index.html. You can learn more about this tool, along with tips and tricks here: https://matthewsetter.com/convert-markdown-to-asciidoc-withpandoc/

Although I have not tried it myself, you can also use Kramdown to convert Markdown into AsciiDoc:

kramdown (sic, not Kramdown or KramDown, just kramdown) is a free MIT-licensed Ruby library for parsing and converting a superset of Markdown. It is completely written in Ruby, supports standard Markdown (with some minor modifications) and various extensions that have been made popular by the PHP Markdown Extra package and Maruku.

https://kramdown.gettalong.org/

Converting Confluence content required a more laborious approach. To achieve this, I first had to export the content to XHTML and then convert it to AsciiDoc with PanDoc.

Challenge 3: Pulling Content from Different Repositories

Use Antora to pull content from different repositories and even branches.

Once all the content had been converted to AsciiDoc, I had to create a folder structure for the docs in the GitHub team repos and find a tool that could pull content from different repos and branches. The solution: Antora.

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

Antora makes it easy for tech writers to create documentation and publish it to the web. As a tech writer, you focus on authoring content in AsciiDoc, Antora’s content markup language. You organize those files into a standard project structure and store them in one or more content (git) repositories. Antora picks up your content from there and transforms it into a website. 

Antora is powered by Asciidoctor, which is a fast text processor and dateing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats

https://antora.org/

Note: You can can bypass installing Antora and get right down to running it. All you need is Docker or podman. I decided to run Antora on Docker for my project and it works like a charm. For more info, see: https://docs.antora.org/antora/2.3/antora-container/

Challenge 4: REST API Documentation

The fourth challenge I was confronted with was how to include the REST API content in the output.

Apparently, there is a way to embed autogenerated API content with Swagger into AsciiDoc files. To achieve this, you just need to:

1. Add the swagger page layout to the Antora UI folder.
2. Create an empty .adoc file.
3. Define a title and a swagger page layout (:page-layout: swagger ) in the file.
4. Include a xref in the header to link to the API content.

You can read this thread to learn more.

I’m currently testing this approach and I hope I can make it work soon. I’ll create a follow-up post to share the findings.

Now my development teams can keep working in GitHub and create all their content in a dev-friendly language. I take care of the playbook to tell Antora where should it pull content from (did I mention that you can even pull content from different repo branches?), and the whole group can access a single output that contains comprehensive and standard documentation for the project.