Motivation for Way of Working
| This is a work in progress. |
Why documentation as code?
First: what does documentation as code even mean? Here’s the definition provided by Write the Docs:
Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code:
Issue Trackers
Version Control (Git)
Plain Text Markup (Markdown, reStructuredText, Asciidoc)
Code Reviews
Automated Tests
This means following the same workflows as development teams, and being integrated in the product team.[…]
Eric Holscher & the Write the Docs community
Benefits to us
Flexibility and interoperability
Having our documentation be simple plaintext files gives us complete freedom in what we wish to do with them. Instead of having them be locked-in in a single integrated solution — as offered by e.g. Microsoft and Atlassian — that dictates a certain way of working and poses a significant commitment, we get to make up our own processes, way of working, tools and languages.
Confluence provides a seamless editing experience with an editor, automated page versioning and the ability to do inline reviewing. However, its versioning capabilities don’t meet our requirements, and the underlying markup standard is proprietary which hinders interoperability.
When adopting the documentation as code philosophy, however, we have the freedom to choose our own markup language(s) and tools for editing documents, a dedicated VCS like Git or Bitbucket, and a publication environment to our own liking. No one solution will limit our possibilities, since we can always choose (or even build) another tool to fix any challenge we might face.
Not least this means we can choose or build a solution that is free. Not having to bother with the complexity and financial hurdle of licensing is a breeze, and of particular significance to a team that is cross-company.
Automation possibilities
Documentation that’s code can be parsed. This means we can write linters and validators which automates lots of governance for us such as checking for dead links and style inconsistencies.
Documentation that’s code can also be generated. For example, a fixed header containing metadata about the document could be generated and included in every document, or a table of attributes could be generated from a data model.
Why AsciiDoc?
We need to choose some language to write our documentation in, and AsciiDoc is our choice.
AsciiDoc is well-standardized, testified by the fact that, as of now, there are no flavors of it
Why not Markdown?
Markdown knows many flavors, i.e. is not well standardized. Moreover, it has very limited expressiveness, at best being able to represent simple tables [1]. Writing Markdown unavoidably involves mixing in quite some HTML, which means you have to write and understand two languages. This is hardly ideal.
For those who are interested: the Asciidoctor documentation contains a more thorough comparison between AsciiDoc and Markdown.
Why not LaTeX or Typst?
We haven’t looked into these languages extensively, since their scope is scientific papers and not the writing of various kinds of documentation such as multipage guides, wikis or books. Because of this we expect to find inadequate support for certain features, most notably cross-referencing between documents.
Furthermore, the language complexity of both is substantial, allowing for powerful features we don’t currently expect to use.
Why not ODT (OpenDocument Text) files?
ODT is a word processor format that is part of the open standard ODF (ISO 26300). It is supported by open source word processors such as LibreOffice Writer, but also by Microsoft Word.
A great advantage of this format is that it makes writing really accessible, since virtually anyone can (easily learn to) write in word processors like Word. So why didn’t we choose ODT?
First of all, this is a binary serialization and therefore doesn’t properly match our requirement of "code". Versioning this is a pain, since no diffs can be generated. This also hinders the ability of reviewing.