Requirements

In my opinion, there are two main types of requirements for Docs as Code:

1. Usability: The more user-friendly Docs as Code is, the more likely people will prefer it over traditional document tools like Word. Ideally, its ease of use should be compelling enough to make users consider it as a viable alternative.

2. Layout: The tools and languages used in a Docs as Code approach must support a variety of layout needs. For instance, it should be straightforward to include images or tables. If a tool doesn't support these features well, it might not meet your needs.

Let’s dive into these requirements and then explore how to fulfill them.

Usability

• Plain Text Source Files

  For me, working with plain text files is both a fundamental part of Docs as Code and a key benefit (see the Benefits). If you treat Docs as Code, your source files should be plain text. That's just how code is written .

• Simple Markup

  Writing source files should be easy for everyone. While some syntax learning is inevitable, it’s crucial that the markup language is accessible. LaTeX, while powerful, can be complex and intimidating as my colleague noted correctly (see the corresponding quote in the introduction). A simpler markup language is preferable.

  (La)TeX's Role in Docs as Code

  The approach I’ll showcase uses Pandoc to convert plain text files into PDF documents. Pandoc uses a (La)TeX template to generate an intermediate TeX file for PDF rendering. Customizing this template may require some (La)TeX knowledge, but ideally, you’ll only need to do this once, if at all, and you can rely on an "expert" if necessary.

• Fast and Easily Generated Previews

  Generating final outputs should be a straightforward process, ideally requiring just a single command. Additionally, previews should be quick and easy to generate, allowing anyone working on the Docs to see updates instantly.

Layout

Note

Different types of documents may require different layout options. Therefore, the following requirements are not universally mandatory but should be adapted to your specific needs.

Info

The requirements listed below are not ranked by importance. I initially intended to prioritize them but realized that document needs vary widely (see the note above).

• Headings, Sections, and Subsections

  This is a basic requirement. Documentation must support creating and hierarchically arranging headings and sections, with automatic numbering if necessary.

• Table of Contents

  If needed, you should be able to generate a table of contents (toc) automatically, along with lists of figures and tables.

• Lists

  If needed, it must be possible to add lists (numbered and just bullet points). It should also be possible to nest lists.

• Code and Code Blocks

  Especially important for software documentation, the ability to add and format code blocks neatly is essential. This feature might also useful for other types of documents.

• Image and Tables

  A picture is worth a thousand words.

  by someone smart

  Including images and tables is a common requirement. The process should be straightforward and efficient.

• Math

  While not always necessary, some contexts demand the inclusion of mathematical expressions. The system should support this if required.

• References and Links

  While not always needed, references and links are often crucial. The ability to reference internal document parts (sections, images, tables, formulas, etc.) and external resources (articles, blogs, websites, etc.) should be available.

• Citations

  Essential for academic documents, the ability to cite other works and generate a bibliography should be supported if needed.

• Footnotes

  Related to references, footnotes are sometimes necessary. They should be easy to include if required.

• Header and Footer

  Headers and footers are standard in many types of documents, including letters and books. Their inclusion should be straightforward if needed.

Now, let's move on to the fulfillment of these requirements.