Falk Sippach
05.01.2025
Documentation as Code uses lightweight markup languages. There is a wide range to choose from. Markdown is currently the most widely used, but AsciiDoc offers important features out of the box. We discuss which language is better suited for documenting software architecture.
By using lightweight text formats, we can create and version our documentation directly in the Git repository – very close to the source code. This makes it easy to compare different versions and restore older versions if necessary. The use of distributed version control systems such as Git allows us to work on documentation offline, for example on the train or in a dead zone. Pull requests and accompanying review processes also allow us to refine content together with colleagues, which greatly improves collaboration. Compared to traditional wikis, which primarily rely on online collaboration, this approach offers the advantage of offline capability. While tools such as MS Word or Google Docs also offer collaborative features, many developers particularly appreciate the ability to edit documentation directly in their familiar development environment or text editor without changing context – just as they do with code.
In addition, we can easily integrate the content serving as a single source of truth in the form of plain text into existing build processes, thus generating a variety of output formats such as HTML, PDF, slides, or even microsites. These modularized text modules can also be flexibly combined to meet the needs of different reader groups. The integration of generated content from models such as UML diagrams, database schemas, or source code is also possible without any problems. Exports from other documentation tools such as Excel, Enterprise Architect, or even from Git history and Jira tickets ensure that our documentation always remains up to date and can be expanded without redundancy.
As is often the case, there are several ways to achieve the same goal. In the field of lightweight markup languages, Markdown has currently established itself as the clear market leader. Almost all web-based, source code-related tools such as code repositories (GitHub, GitLab, etc.) and many wikis already offer support for this format as standard.
Although AsciiDoc is slightly older than Markdown, it did not gain much traction initially. It was only with its reimplementation as Asciidoctor in 2013, first in Ruby and later also as ports in Java and JavaScript, that AsciiDoc gained increasing popularity and gradually grew into a serious alternative to Markdown. Since 2020, work has also been underway on standardization under the umbrella of the Eclipse Foundation.
| Category | Markdown | AsciiDoc |
|---|---|---|
| Inventor/Author | John Gruber (in collaboration with Aaron Swartz) | Stuart Rackham |
| Year of publication | 2004 | 2002 |
| License type | Open source, various implementations (often MIT or BSD) | Open Source, GPLv2 (AsciiDoc), MIT (AsciiDoctor) |
| Main purpose | Easy creation of web texts and documentation | Extensive technical documentation, e.g. for software projects |
| Syntax complexity | Very simple, well suited for beginners | Somewhat more complex than Markdown, but powerful and flexible |
| Expandability | Limited support, extensions mostly through specific parsers | Highly extensible with macros and custom styles |
| Tool support | Broad support in editors and platforms (e.g., GitHub, VS Code) | Well supported by editors such as Asciidoctor, GitHub, and IDEs |
| Popularity | Very common, especially in web projects and documentation | Particularly popular in software and technical documentation |
| Standardization | CommonMark als Standard, auch GitHub Flavored Markdown (GFM) | Asciidoctor as the de facto standard, standardization underway at Eclipse Foundation |
| Special features | Simple syntax, easy to learn, many options thanks to variants | Support for document modularization, diagrams, tables, cross-references, and CSS-like styles |
Markdown is the de facto standard, available in numerous tools, easy to learn, and particularly popular with technicians for documentation purposes.
| 👍 | 👎 |
|---|---|
| 80% solution for simple markup | For more sophisticated documentation, important concepts such as tables, includes, TOC, admonitions, attributes/variables, anchors, footnotes, syntax highlighting, etc. are missing. |
| Very widespread, large selection of tools | The missing concepts are offered by countless extensions in very different and incompatible ways (there are a multitude of Markdown dialects). |
| Standard feature set that is manageable but sufficient for simple text | Depending on the toolchain, not all dialects may be supported, and portability between dialects may be difficult. |
The feature set includes:
<hr/>)On the other hand, interesting features are missing (or are only supported in different ways via dialects):
AsciiDoc sounds rather old-fashioned, and perhaps it should be renamed UnicodeDoc, UTF8Doc, or something similar. But apart from that, it offers some powerful and interesting features.
| 👍 | 👎 |
|---|---|
| Markdown-compatible superset, facilitates migration | less widespread and less tool support |
| Developed for demanding technical documentation | |
| Powerful syntax with powerful processor AsciiDoctor (implemented in Ruby) | |
| Can also be used on the Java platform with JRuby and in the JavaScript environment with Opal. | |
| Very vibrant ecosystem (many plugins, e.g., for diagrams-as-code with PlantUML) | |
| Good editors and preview tools | |
| Easy and flexible integration into common build process tools | |
| Standardization of AsciiDoc underway at the Eclipse Foundation |
The special features of AsciiDoc are:
Which tool is the right one? As is so often the case, it depends. There is no universal solution. AsciiDoc is particularly ahead of the game when it comes to technical documentation. However, Markdown is often the more practical choice thanks to its ease of use, widespread popularity, and comprehensive tool support. Markdown is usually sufficient for simple documents such as README.md files in Git repositories. However, when it comes to more complex requirements, you quickly reach limits that either require you to forego advanced formatting or use a specific Markdown dialect, which makes portability more difficult.
For more demanding projects, such as documenting a software architecture, it is advisable to use the more powerful AsciiDoc directly. Although it requires a specialized tool chain, once this is set up, documentation becomes less stressful in the long term. In addition, the standardization process is progressing, which suggests broader acceptance and use in the future.
| Criteria | AsciiDoc | Markdown |
|---|---|---|
| Learning curve | Steeper, more complex syntax | Simple, easy to learn |
| Feature set | Very extensive (e.g., complex documents, diagrams, metadata) | Limited, primarily suitable for simple to medium-sized documents |
| Tool support | Less common, dependency on Asciidoctor | Very widespread, native support in many tools |
| Flexibility | High (e.g., attributes, extensions) | Limited, often restricted to basic functions |
| Compatibility | Not natively supported everywhere | Universally supported (e.g., GitHub, CI/CD tools) |
| Suitability for beginners | Less suitable, more extensive documentation requires configuration | Very suitable, easy start |
| Complex structures | Ideal for large, structured documentation | Weaknesses in complex hierarchies and links |
| Performance | Slower generation for large projects | Faster, especially for simple projects |
| Use cases | Ideal for technical documentation and demanding requirements | Perfect for quick, easy documentation |
| Standardization | Uniform and clearly defined syntax | Different dialects lead to inconsistencies |
| Community | Smaller, but focused | Large, with many resources and tutorials |
The choice of markup language actually depends on the respective ecosystem. Different formats are better supported depending on the programming language. AsciiDoc, for example, is widely used in the Java environment, while reStructuredText is considered a powerful tool in the Python world. However, reStructuredText requires more intensive training. This could be an interesting topic for another blog post.