A few days ago I had an interesting conversation on the pros and cons of Markdown for technical documentation with Ed Marsh (Goldman Sachs) and Eric Holscher (Read the Docs) in a webinar hosted by Scott Abel (The Content Wrangler). Here are some of the things I said during the webinar, transcribed and edited for clarity.
“Markdown is around. It’s like what happened with Microsoft Word a few decades ago: you could turn on a computer and [Word] was there. You could open a DOC file everywhere. And with Markdown, I think we are witnessing a very similar phenomenon […] It’s kind of an unspoken standard. It’s just sheer availability. Almost every tool has some way of entering Markdown and getting some formatted text out. So it’s not as much a conscious decision as a realization that, well, we should start with something. And Markdown is already there.”
“I think the greatest limitation of Markdown is the lack of standardization. We are going a little deeper here, but for something that is being used by the whole developer’s community at some point every week, the lack of standardization is incredible. Every standard you see out there, every program and language, everything is backed up by important software companies defining what the standard should be. This is not currently the case for Markdown.
There is no big organization, council, committee, anything. It leaves software developers alone to wonder how they should render the elements in Markdown. How should they do things like tables? Sometimes it’s even harder to translate between dialects of Markdown. And you have to resort to tools like Pandoc, which is fantastic, by the way, but yeah, you essentially need translators to do things in between.”
“The best way to picture the Markdown journey is Choose Your Own Complexity. You start with with the very basics and you have a tool that everyone can use, but then you have to decide on many things. You have to decide how you will render the documentation, what sort of Markdown flavor you’re gonna use, how you’re gonna extend it, because eventually you’ll need to extend it. And, you know, if you start from Markdown, eventually you will have to put some thought to things like future content migrations: Will we be able to move this content somewhere else, maybe a CMS or a headless CMS or something similar? The complexity really isn’t there at the beginning, and it’s a bit misleading; then it really gets hairy very fast.”
“There’s a risk and an opportunity in [adopting Markdown]: the opportunity is that you can get developers in your teams in engineering pretty excited about this Rube-Goldberg machine, and they might help you in building it. The risk is that you may end up building a machine that you didn’t really want at the beginning.
Remember that scene where Han Solo is punching the Millennium Falcon because the hyperdrive does not engage? That happens a lot in with docs-as-code and Markdown. And it’s kind of fun […], you get together with the engineers and try to solve the situation together, and the writer become a little bit engineer, the engineer become a little bit writer. But it’s not really sustainable in the long run. I think it’s a good phase, but it cannot go on forever.”
“If you are working in a highly regulated environment, like aviation or finance, you need documentation to be accurate. You need documentation from the start because that’s what the law demands. And there might be lives at stake. For software it’s slightly different: it’s harder to just go to a startup and say “we are gonna use this fantastic XML based tool from the very beginning”. It’s a hard sell. So what happens is that Markdown allows you to be the ninja content strategist: you entered the organization, you are not asking folks to learn anything different than what they know. And then you start building on it.
You have to realize that this is a Trojan horse strategy. Like, you want the docs to be the product, fine. This is what all tech writers want eventually. But be very careful about the product not being, for example, the pipelines or the site you’re gonna render. I mean, that might be part of the product. The product is the docs, right? But you have to enter a software company with Markdown with that mindset. Otherwise it will just turn into something that’s not even a feature, and lose importance.
The value of Markdown is that it allow us to enter with very low friction into worlds that maybe haven’t even thought about docs.”
At some point during the webinar, a viewer asked us about something I wrote on Linkedin. Here’s my original quote:
We don’t use Markdown for docs because it’s better. We use Markdown for docs because most software companies haven’t even started their documentation efforts yet and we need a scratchpad every developer can use and understand. It’s a sociological choice, not a technological one.