Using AsciiDoc (AsciiDoctor) for Documenting Everything

Using AsciiDoc (AsciiDoctor) for Documenting Everything

As we write things from READMEs, to actual documentation, to this blog, are we to use a unified documentation format? Are Markdown or AsciiDoc the answer? In my opinion yes, and let’s see why.

Having something that’s available as a plain text file makes it easier for both editing and reviewing. Spinning up a basic text editor is instant, versus opening Word, or Google Docs. Automating publishing in different formats is easy now, and is script-able.

In the world of text formats, I’m of the opinion that Markdown is easier for the eyes. I find it easier to read Markdown documents in a text editor than AsciiDoc, and is better supported in more tools and websites. Even VisualStudio Code has live editing support bundled in for Markdown.

These being said, even if I consider Markdown superior for smaller documents, I’m using AsciiDoc. What makes AsciiDoc appealing to me is the multi-publishing support, and while the syntax is a bit more weird, it allows for better control on the output.

A while back I analyzed all the document types that I needed to build, and decided I wanted something version-able, reasonable to analyze in a git diff. I had:

1. readme files - unfortunately only github renders them. Not docker hub, nor gogs. I ended up writing most of my README files in the end as Markdown. :(

2. book like pdf documentation - this is where AsciiDoc shines, because you can just output a PDF. I’m using asciidoctor-pdf to generate a PDF and the html germanium documentation from the same sources.

3. website - yes, this post is actually written in AsciiDoc.

4. chm help - This is how the help for the Germanium Selector Builder is built, so when someone presses F1 they get the actual Windows Help to open.

In the end I think whatever you pick, Markdown, or the AsciiDoc/AsciiDoctor combo, you need to try to align all your documentation efforts around the same format. Don’t use Word/google docs for a document, Markdown for another, and RST for a third.

Then only you have the unique chance of simplifying both the writing process, and the tooling around it, so your focus stays on generating the actual meaningful content. And at the end of it all, you also diversify your options on the publishing formats.

Go write something amazing :)

Article Photo from Pexels: https://www.pexels.com/photo/batch-books-document-education-357514/