Markdown for Technical Documentation

It seems like this advice comes along periodically: Don’t use Markdown for technical documentation. Hillel Wayne is the most recent plea to hit hacker news, but there have been others.

Hillel Wayne, Please don’t write your documentation in Markdown

Markdown cannot carry data. There’s no way to imbue properties into text using markdown. Good documentation is all about the semantic markup. A “definition” is not just a different formatting or like. It means there’s actually a concept of a “definition” as a discrete concept in your documentation.

Matthew Butterick, in Pollen: the book is a program:

Markdown is a limiting format for authors. Why? Because Markdown is merely shorthand notation for HTML tags. As such, it has three problems: it’s not semantic, it only covers a limited subset of HTML tags, and it can’t be extended by an author.

Eric Holscher, Why You Shouldn’t Use “Markdown” for Documentation

Though many people have added extensions to Markdown, almost none have any kind of semantic meaning. This means that you can’t write a Class or a Warning, you can only write text.

Mister Gold, Stop Using Markdown For Documentation

With Markdown you can only write text. It means that if you need to grab the reader’s attention with some kind of notes or tips, you have to embed HTML.

I have focused on the lack of semantic data in all these criticisms, because I think it is the most important drawback. The lack of semantic meaning in markdown makes in unsuitable for many technical writing tasks. Yet, I still write in markdown. This post is in markdown. There are a couple of reasons:

  1. Its easy. I never forget the syntax. This may be because it is so limited, but it makes it easy to do simple documents.
  2. It’s ubiquitous. The fact that there are so many different markdown parsers is not problem, its a strength. It’s usually trivial to add markdown to a system or workflow, regardless of the environment

What are the alternatives?

ReStructurexText – If I were writing a book, I would probably use ReStructuredText. It is extensible, so you can add your own “roles”. But the syntax is pretty hard to remember. For example, here is the image syntax:

.. image:: images/biohazard.png
    :height: 100
    :width: 200
    :scale: 50
    :alt: alternate text

Of course, the benefit is that the image tag has a height, width, and scale: something few markdown parsers support. It’s heavily tied to Python, which is something I’m comfortable with. It’s also heavily tied to a single implementation in docutils.

AsciiDoc – The syntax is more in the spirit of markdown. It seems to have coalesced around a Ruby implementation, and left the original python implementation languishing[1]. I was unhappy with the HTML produced by asciidoctor is styled entirely by div tags. Title ; just styles applied to named div tags.

Pollen – Very nice system. The fact it requires Racket is both admirable and a real-world pain. I gave up after trying to write my own pollen command. Trying to debug the unexpected return type from a nested s-expresion did me in.

For now, I stay with markdown, and all it’s shortcomings.

  1. There are also two competing versions of aciidoc for python3: asciidoc-py3 and asciidoc3  ↩

Remote Cheese Tasting

In the spirit of supporting our local business during the pandemic, we signed up for a cheese-tasing course with Antonelli’s. We picked up a half pound of cheese from their shop: a pre-selected sampling of seven different cheeses. Then we embellished it with a little prosciutto, Castelvetrano olives, a baguette, and some wine. We then tuned into their video stream while they talked us through the full tasting menu. It was great, especially considering they had never streamed a tasting before and rushed into it with about a week’s preparation.

A cheese plate with wine and bread.

Three Days, Three Rings

One thing I noticed during these coronavirus work-at-home days is how absolutely sedentary I am when working from home. I’ve worked from home in other jobs, but I really notice it now. My Apple Watch detects essentially zero exercise, and very little activity. At work, all the small trips to the water fountain, to the restroom, to the cafeteria, they all add up. They don’t close my rings, but they at least make it look like I did something besides sit on my butt all day. At home all of those little trips are about 20 feet away, max.

In the last few days I’ve been making an effort to get out and close my exercise ring. I no longer have a commute, so that gives me an extra 45 minutes to an hour I can devote to exercise. I’ve been getting my rings closed, and breaking free of the stay-at-home ennui.

WordPress Hosting

While I’m on the topic of WordPress, I found a new hosting provider. I run a small family site. Even though it’s small, it has a lot of specific needs:

  • It’s very image-heavy, so it needs lots of storage space
  • I need to send out email notifications at various events
  • Users need to be able to post by sending email
  • It needs to be robust and reliable, so I don’t spend a lot of time chasing down issues.

We’ve tried various hosted solutions. was hosting it for a while. At some point, they made changes to their user profile settings, and some users were having issues I couldn’t help them with. I moved to self-hosted so that I had enough control to address these issues. Besides, our disk usage was growing and I was likely to get priced out of the free plan.

There are several shared plans that I looked into. They often come with an email serve I can use, but my experience with them hasn’t been great. Running a DigitalOcean droplet works great, until it doesn’t. Then it takes all Saturday to figure out what’s goin on. There is a next tier of plans that help you manage a VPS. ServerPilot and RunCloud are a couple of examples. They help with the setup of the web server and database, but after that, you’re on your own. They don’t have a mail server, and only the foolhardy run their own mail server. Then I found CloudWays. It does all the stuff ServerPilot and RunCloud do, but they also offer mail server add-on. For $1/month, I can add a RackSpace mailbox. I use this for incoming post-by-email traffic. Then for a few cents per 1000, they offer an outgoing SMTP server. I could (and have) patched this all together with a service like Migadu. But having it integrated with the server is a big plus.

New Theme, Take One

Well, here I am, with a new theme. I’m giving GeneratePress a whirl after discovering it on the WordPress subreddit. I want a pretty simple, text-heavy site. I don’t have a store, a shopping cart, or any heavy layout needs. My main interest is fonts and typography, and this gives me enough control. I can also tweak various layout elements as much as I need.

There’s a pretty capable free versions, I paid the $50 for the pro upgrade. That pricing is perfect: it makes me reasonably confident the theme will be supported and upgraded, but it’s cheap enough for a hobby site with no income.

If you looking for more like this, Astra is another one that came up, with a similar pricing structure. I don’t have a particularly good reason to choose GeneratePress over Astra. I think it was partly that the pricing and the product info gave me the impression their market is individual bloggers, whereas Astra is trying to address agencies and WordPress freelancers. Like I said, not a great reason, but they both looked good, and I need some basis to make a decision. Hopefully there is no Take Two sequel to this post, but if there is, it will probably be Astra.