|
| 1 | +# Markup languages for documentation |
| 2 | + |
| 3 | +## Presenter |
| 4 | + |
| 5 | +[Vladimir Izmalkov](https://www.linkedin.com/in/vaizmalkov/) |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +<iframe width="560" height="315" src="https://www.youtube.com/embed/C0V0A8GGfAs?si=gQpDaRBp5fXw9Og7" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +Documentation markup languages fall into two broad categories: lightweight markup languages and Extensible Markup Language (XML)-based formats. These tools serve the same goal but take different approaches to content creation and management. |
| 14 | + |
| 15 | +## Lightweight markup languages |
| 16 | + |
| 17 | +Markdown was developed in 2004 as a simple text-to-HTML conversion tool. It was originally created for web publishing rather than documentation, but teams have now adopted it across countless documentation projects. The format processes through hundreds of different tools, from static site generators like [Jekyll](https://jekyllrb.com/) and [Hugo](https://gohugo.io/) to documentation platforms like [GitBook](https://www.gitbook.com/) and [Docusaurus](https://docusaurus.io/). |
| 18 | + |
| 19 | +Markdown offers several advantages: |
| 20 | + |
| 21 | +* Its simple syntax requires minimal learning time and allows writers to focus on content rather than formatting. |
| 22 | +* The format is widely adopted across messaging platforms, content management systems (CMS), and development tools. |
| 23 | +* Writers can embed HTML directly when they need advanced formatting options. |
| 24 | +* The extensive ecosystem makes integration straightforward for most projects. |
| 25 | + |
| 26 | +Markdown has some limitations that affect larger documentation projects. Some of these limitations are: |
| 27 | + |
| 28 | +* The core specification provides limited features compared to other formats. |
| 29 | +* Tables are problematic since they offer no advanced formatting options like merged cells or complex layouts. |
| 30 | +* Markdown lacks include functionality, which prevents content reuse across multiple files. |
| 31 | +* Advanced formatting often requires HTML embedding, making content harder to maintain. |
| 32 | + |
| 33 | +Despite the limitations, Markdown now has different flavours to address some of these issues. Each flavour adds new features but also creates potential compatibility problems between implementations. Some of these flavours include: |
| 34 | + |
| 35 | +* GitHub Flavoured Markdown (GFM) |
| 36 | +* Standard Markdown |
| 37 | +* MultiMarkdown |
| 38 | +* Markdown Extra |
| 39 | +* Pandoc Markdown |
| 40 | +* R Markdown |
| 41 | + |
| 42 | +### reStructuredText |
| 43 | + |
| 44 | +reStructuredText was developed in 2001 as part of the Python Docutils project. The format processes primarily through [Sphinx](https://www.sphinx-doc.org/en/master/) and Docutils. |
| 45 | + |
| 46 | +reStructuredText offers significant advantages for teams comfortable with Python ecosystems. These advantages include: |
| 47 | + |
| 48 | +* The format supports extensive customisation through Python code. |
| 49 | +* It maintains consistent standardisation, unlike Markdown's fragmented ecosystem. |
| 50 | +* It offers rich features out of the box that exceed Markdown's basic capabilities. |
| 51 | + |
| 52 | +However, reStructuredText has some limitations, and they include: |
| 53 | + |
| 54 | +* It requires more verbose syntax and uses more special symbols than Markdown. |
| 55 | +* Teams often find the syntax confusing when switching between Markdown and reStructuredText because they appear similar but use different conventions. |
| 56 | +* Tool support remains more limited than Markdown's ecosystem. |
| 57 | +* Advanced features often require Python programming knowledge. |
| 58 | + |
| 59 | +### AsciiDoc |
| 60 | + |
| 61 | +AsciiDoc was developed in 2002. Today, it's commonly processed using [Asciidoctor](https://asciidoctor.org/), a popular processor, and [Antora](https://antora.org/), a documentation site generator that builds on Asciidoctor. |
| 62 | + |
| 63 | +AsciiDoc is the most feature-rich out-of-the-box solution among lightweight markup languages. The format has the following advantages: |
| 64 | + |
| 65 | +* It provides extensive table formatting options, including merged cells, nested tables, and complex layouts. |
| 66 | +* Its syntax is easy to read, particularly for code blocks and complex structures. |
| 67 | +* It maintains strong standardisation through its official specification while allowing macro extensions through Antora. |
| 68 | + |
| 69 | +AsciiDoc also has some limitations, and they include: |
| 70 | + |
| 71 | +* It's less common compared to Markdown and reStructuredText. |
| 72 | +* It has limited support. |
| 73 | + |
| 74 | +## XML-based formats |
| 75 | + |
| 76 | +XML was originally designed for data storage and transmission rather than human-readable writing. Due to this, documentation formats built on XML inherit its verbosity and complexity characteristics. These formats transform XML's data-focused structure into frameworks suitable for technical writing and content management. |
| 77 | + |
| 78 | +### Darwin Information Typing Architecture (DITA) |
| 79 | + |
| 80 | +DITA focuses on structured, topic-based content creation. The format’s modular approach supports content reuse across multiple documents. DITA also excels at conditional publishing, which lets teams include or exclude content based on build conditions. It's best suited for large-scale operations with complex documentation sets, where teams need to manage intricate content relationships. |
| 81 | + |
| 82 | +### DocBook |
| 83 | + |
| 84 | +DocBook targets traditional publishing workflows for books and articles. It optimises for structured content that flows from beginning to end in a linear fashion. DocBook supports cross-media publishing and offers extensive customisation options for teams that need professional publishing capabilities. The format works well for book-style documentation but lacks DITA's modular, topic-based approach. |
| 85 | + |
| 86 | +### S1000D |
| 87 | + |
| 88 | +S1000D serves specialised compliance requirements in regulated industries. The format follows rigid structural requirements and supports comprehensive compliance documentation needs. Teams in regulated environments often find S1000D mandatory rather than optional. The format includes its own version control systems and data models for managing complex technical documentation that must meet specific industry formats. |
| 89 | + |
| 90 | +## Making a selection |
| 91 | + |
| 92 | +Choosing between lightweight markup languages and XML-based formats depends on your project's needs and your team's situation. Lightweight markup languages are simple, open-source, and mostly use Git for version control. They work well for open-source projects and smaller documentation sets, but may need extra setup and adjustments. On the other hand, XML-based formats offer complete solutions out of the box. They are best for large, complex, or compliance-heavy documentation, but can be costly and might lock you into a specific vendor. |
| 93 | + |
| 94 | +For most teams, starting with Markdown makes sense because it's simple and widely adopted. It helps avoid many of the challenges that come with more complex tools. Teams can first evaluate whether Markdown meets their needs, then identify any missing features. Common gaps include advanced table formatting, content reuse, and specialized formatting. |
| 95 | + |
| 96 | +If your team is comfortable with Python, reStructuredText is a good choice due to its customisation through Sphinx. If you want lots of features without much programming, then consider adopting AsciiDoc. |
| 97 | + |
| 98 | +## The docs-as-code approach |
| 99 | + |
| 100 | +The docs-as-code approach treats documentation content like source code. This method is used in various fields, like **infrastructure as code**. The process involves storing content in a repository and using a builder to assemble the final documentation. This method uses Version Control Systems (VCS) like Git. VCS is used to track changes, view historical data, and manage contributions. |
| 101 | + |
| 102 | +Docs-as-code remains the dominant approach in both lightweight markup languages and XML-based solutions. The docs-as-code process has three main components: |
| 103 | + |
| 104 | +* **Source code:** This includes all the documentation content, images, and other necessary resources. All these files are stored in a repository, preferably using a VCS. |
| 105 | +* **Builder:** This tool takes the source code and applies a design template to create the final, published documentation. |
| 106 | +* **Published documentation:** This is the final result generated through the builder’s assembly. |
| 107 | + |
| 108 | +A key aspect of this process is that when you change the source content, the published documentation also changes. The builder usually stays the same, ensuring consistency. The use of a VCS is crucial because it lets you store and track all changes over time, allowing you to build older versions of the documentation at any point. |
| 109 | + |
| 110 | +### Limitations of docs-as-code |
| 111 | + |
| 112 | +The limitations of docs-as-code are as follows: |
| 113 | + |
| 114 | +* It requires additional effort and skills to use a VCS and to set up the documentation builder. |
| 115 | +* There is a lack of a What You See Is What You Get (WYSIWYG) editor, so you don't see the final rendered output until the document is built. |
| 116 | +* You have to combine different tools to make them work together. This requires knowledge and setup efforts. |
| 117 | + |
| 118 | +## Markup language choice at Canonical |
| 119 | + |
| 120 | +Canonical supports its wide range of software and active community by choosing formats carefully. The company mainly uses Markdown because it's popular and easy for contributors to use. |
| 121 | + |
| 122 | +Some Canonical projects use Discourse, a platform that natively supports Markdown, as the main repository for their docs. Other projects use Sphinx and [Read the Docs](https://about.readthedocs.com/). Sphinx is the primary tool for reStructuredText, but a plug-in called [MyST](https://mystmd.org/) allows the use of Markdown within the Sphinx framework. This plug-in allows them to leverage Markdown's simplicity while still using a powerful builder like Sphinx. |
0 commit comments