> barriers to producing documentation--should be minimized. Writing well is difficult enough!

Writing is a demanding kind of encoding. At the same time, we all expect but rarely get good, accessible, searchable documentation. Why? The one barrier that cannot be removed is the need to retain semantic structure.

In TFA, the author writes:

    The Bad -- We don’t know what we want.

It's exactly this. We fail to recognise why we write and then we fail to express it. We don't write technical documentation for the equivalent of KLOCs. Writing something useful and meaningful -- not just performative filler for KPIs or SEO enshittification -- requires structure. Anything valuable that can't be retrieved effectively is lost. Imagine losing actual code or database rows at the same rate.

We consistently fail to manage meaning. It's strikingly paradoxical because the art of programming is all about meaning. We organise code semantically because it is essential to do so (not just for compiling, but also) for extending/refactoring/review/retrieval/understanding.

We need to write with the same considerations. This need not be complicated. Yet we persist in using the wrong utensils for the recipe.

> Markdown is the best compromise we know of

It reduces keystrokes and makes the handraulic act of writing easier. But... it addresses only part of the problem.

As an example of a small improvement, HTML5 offers a minimal set of semantic tags: <summary> <article> <main> <section> <details> <aside> <figure> <figcaption> <time>

It may be a simplistic set of tags, but it is an improvement over easy-to-type text blobs.