Blog Marc van Kessel
MS Word is no place for documentation. A text file is.
My daughter is sent an MS Word template as the basis for her bachelor's thesis. During my own IT studies we already worked with LaTeX; serious documentation belongs in plain text, separate from any layout.
My daughter is sent an MS Word template as the basis for her bachelor’s thesis.
That surprised me, and honestly I find it baffling. During my own IT studies we already worked with LaTeX: no MS Word, no mouse, no quickly formatting something by hand.
Serious documentation does not belong in MS Word. It belongs in a text file.
An academic legacy: content over layout
LaTeX is popular in the academic world, and that is no coincidence. Researchers write articles that are later bundled into conference proceedings and journals with a uniform look. The arrangement is simple: you provide structure and content, the publisher takes care of the formatting.
That separation is still in every modern markup language. Whether it’s LaTeX, AsciiDoc, or the now ubiquitous Markdown: you describe what something is about, not how it should look. A paragraph is a paragraph, a heading is a heading, a list is a list. The formatting comes later, and varies from publication to publication.
Text files are timeless
Another argument is practical. You can still open a plain text file in twenty years. It costs you no licence, no specific version of an editor, no cloud account. That sounds minor, but for documentation that has to last years or decades, it is everything.
Version control (Git) and plain text are made for each other: every change is visible line by line, two people can write at the same time and have their work merged, and looking up old versions is a matter of a single command. Try that with a fifty-page MS Word document.
One source, many publications
A markup language can publish the same source in many forms. The content of this website is written in AsciiDoc; the page you are reading now comes from a plain text file, without formatting. The technical documentation of our framework and ERP system comes straight from the Java projects in which we build the software, with the same version control, in the same format.
The same text can become a PDF, a handout, an internal wiki, a part of a product page. One source, many destinations. That is not a gimmick; it is exactly what makes documentation durable.
A look under the hood
Below is the start of this blog post, as I wrote it in plain text (AsciiDoc).
[quote.pullquote]
My daughter is sent an MS Word template as the basis for her bachelor's thesis.
That surprised me, and honestly I find it baffling. During my own IT studies we
already worked with https://en.wikipedia.org/wiki/LaTeX[LaTeX]: no
https://en.wikipedia.org/wiki/Microsoft_Word[MS Word], no mouse, no _quickly
formatting something by hand_.
Serious documentation does not belong in MS Word. It belongs in a text file.
== An academic legacy: content over layout
LaTeX is popular in the academic world, and that is no coincidence.Two = make a heading, a blank line starts a new paragraph. The quote tag only
indicates that it is a quote, not how it should be displayed. The rest, font,
colour, margins, is handled by the site when it builds.
A personal disappointment
Ten years ago I wrote extensive technical documentation in AsciiDoc for a large Java project, alongside the code, under the same version control. With every release the documentation came along automatically.
A year later I came back to that client. The AsciiDoc was gone, developers had moved everything into one MS Word document of a few hundred pages, completely separate from the code. I had to bite my tongue. In the end the customer is king; all we can do is advise.
But the tide is turning
In software, Markdown has long since become the standard, and with the arrival of AI it is becoming better known to the general public. READMEs, technical blogs, AI skills, it’s all in text files. Ten years ago I still had to explain this; today I rarely do.
Documentation is not about how it looks. It is about what it says, and whether it is still readable and correct a few years from now.
In the software and AI world, that realisation has sunk in. At university, apparently, not yet, as that MS Word template of my daughter’s shows.