Don’t Use Markdown for Documentation

http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

by ericholscher • 10 years ago

121 75 10 years ago

mmagin• 10 years ago

TIL that Read The Docs is a product and not just a condescendingly-named website with mirrors of python docs. :)

102030485868• 10 years ago

Ah. This reminds me of a great discussion that happened over at the Rust Internals forum about which markup language to use for documentation. [0]

tl;dr: Markdown won.

[0] https://internals.rust-lang.org/t/rustdoc-restructuredtext-v...

tirus• 10 years ago

And then there's CommonMark: http://commonmark.org/

They aim to standardize the "markdown-like" formats into a single unified one. It's not done yet but it's certainly better than everyone for themselves.

manyxcxi• 10 years ago

This kind of reminds me of the XKCD[0] Standards comic strip. I love writing initial documentation in Markdown because I basically just punch out a text file with line breaks separating my sections/headers and add in some of the markup quickly after I get my content written.

It really is annoying though when I have to be careful about a convention that I'm using if I'm putting a README in BitBucket vs GitHub vs whatever else. Generally, if I'm just sticking to headers, lists, and quotes, I have no problem and everything works and I don't pay it another thought.

[0] https://xkcd.com/927

emodendroket2• 10 years ago

To be fair, the article literally links to that and mentions it as a possible solution.

cryptos• 10 years ago

Does anyone remember Creole wiki markup? It was born in a time when each wiki created its own syntax. Creole should become the standard for wikis, but it never got traction. I fear that it will be the same with commonmark.

emodendroket2• 10 years ago

Probably would have worked better if they were allowed to call it "Standard Markdown" or had been able to get Gruber aboard.

danielvf3• 10 years ago

Markdown is wildly popular because Markdown is easy to write and read unprocessed. At a basic level, it's little more a few conventions for writing text.

RST, used by Sphinx, isn't quite as easy to write or to read. There are plenty of gotchas. RST adds friction.

Using Sphinx also requires you to setup and configure Sphinx for your project - even more friction early on.

The world is far better for having Markdown, and it's the right choice for most projects.

However, there is indeed a place for more complicated projects to take on the workload of a more complicated documentation system so that they can help user and developers better. Django's amazing documentation is an example of this, and a major reason for the success of the project.

mercurial• 10 years ago

RST, used by Sphinx, isn't quite as easy to write or to read. There are plenty of gotchas. RST adds friction.

What gotchas are you thinking about?

Using Sphinx also requires you to setup and configure Sphinx for your project - even more friction early on.

You can perfectly well RST without Sphinx, it depends what you want to use it for. Obviously, if you want to use for Sphinx, you need Sphinx. But otherwise, you can perfectly well use rst2pdf or rst2html with a standard RST document.

danielvf3• 10 years ago

The format for code blocks in Markdown is to indent by four or more spaces.

The format for RST/Sphinx code blocks is to type two periods, a space, the word "code-block", then two colons, then exactly two new lines, and at last you can write your code. Indented with four spaces. Also, you have to make sure there is a blank line between that "code-block" magic line and your preceding text. In practice, I usually manage to screw some part of this up.

The extra complexity and cognitive load makes it much harder for a developer to just write thoughts.

peatmoss• 10 years ago

If you're using Github and/or Pandoc for things, you can pretty much drop org-mode in as a replacement. It doesn't even require emacs :-)

In general, I find org-mode about as easy as Markdown, but with support for things like cross-references that are sadly lacking in standard Markdown.

geerlingguy• 10 years ago

After having written a fairly popular 400+ page book, and dozens of documentation sets in Markdown (and having worked on a few in other languages), I have to say—Markdown is _good enough_.

The other syntaxes mentioned will not be mainstream enough to gain critical mass for some time, if at all. Markdown, for many projects, is literally plain text with some added frills for headings, lists, and code blocks.

Yes, adding a code snippet inside a table cell inside a list can be a pain-inducing experience (especially until CommonMark settles things down a bit)... but that's about .05% of anything I've ever written, and for those particular instances, I fall back to HTML, which is completely compliant and much less ambiguous.

For myself, and for most of the projects I've worked with and maintained, you need documentation to be dead simple in syntax, and requiring a syntax with even less adoption than Markdown is an easy way to cause users who would've otherwise contributed doc fixes and updates behind.

kazinator4• 10 years ago

I wrote a 400+ man page in troff!

http://nongnu.org/txr/txr-manpage.pdf

Welcome to the BDSM club.

Big Document in Shitty Markup.

dguaraglia• 10 years ago

troff! Wow.

jhoechtl• 10 years ago

How was your experience? What tools did you use, editor? Was it troff, Plan9 roff, neatroff?

nils-m-holm• 10 years ago

Troff is not that bad, really! I started typesetting my books in Troff (even with my own macro package), then tried TeX and Lout, and I think I'll actually return to Troff, if I should decide to write another book. Simplicity is good!

Oh, and I have used homebrew markdown preprocessors to write books (e.g. http://t3x.org/s9fes/edoc.html). Great fun!

galonk• 10 years ago

With all due respect, a book is nothing like technical documentation. The biggest issue with documentation is that it needs a lot of structure. To do interesting things you need to be able to mark certain passages of text as special (e.g. this term is in the glossary; this block is a method signature), and you need hierarchical structure (e.g. you can't just have bullets points that appear more or less indented, you need some bullet points to be children of other bullet points). That's what Markdown is terrible at.

gberger• 10 years ago

“Markdown” is the most commonly used markup language on the internet.

Wouldn't that be HTML? :)

parenthephobia2• 10 years ago

The fundamental complaint seems to be that the portable subset of Markdown doesn't allow for extending with new types of blocks.

I find this an unconvincing argument against Markdown per se. It's an argument against writing in the portable subset of Markdown, but why would anyone need to do that in their documentation? It isn't as if specific Markdown implementations are hard to come by, or that there is a context where it would be onerously hard to mandate a specific implementation.

Not to say that Markdown's fragmentation isn't a bad thing. It's annoying, especially when you do use different implementations in different pieces of software and you're trying to remember whether this version supports tables, say, and what the syntax might be.

“Markdown” is the most commonly used markup language on the internet.

That'll be HTML. :) Not just being facetious. HTML is certainly an option for documentation, albeit not one I'd be totally happy with.

You also can’t migrate Markdown easily to another markup language (Asciidoc or RST), because Pandoc and other conversion tools won’t support your flavor’s extensions.

Unless those flavours are Markdown Extra or Github or CommonMark, which pandoc does support. Pandoc also supports adding specific syntax extensions ad-hoc, as noted in its fine documentation. Although, I'd question why this would be an issue in practical terms.

3327• 10 years ago

Markdown actually works great for documentation.

stick a certain version and do not change it.

the article is likely bias as writes states he works for read the docs.

ajford3• 10 years ago

I love Markdown. I enjoy RST. I think, like programming, they have their own merits and use cases.

Markdown is a lot less verbose in my opinion than RST. It's not intentional, nor is it insurmountable, but little things like inline code, hyperlinks, defined subsection levels, and many more all add up to a bit of cognitive load that I don't need for all situations. When I'm writing quick notes for a meeting, or trying to jot down something, RST is a bit much. Which perhaps isn't what this article is really harping on.

But when my quick notes to myself about a project turn long-winded and become more of functional docs, it can be a pain to rewrite that into rst.

I do, however, tend to use RST when I sit down to write documentation for a project. I even tend to use it when documenting firmware and hardware portions of projects. This of course due to the so far poor handling of images in Markdown.

So like I said above, they are tools. One may be better suited to something than the other. But thus is the nature of tools. Use the right tool for the right job whenever possible.

parenthephobia2• 10 years ago

If I need a level of control over the text that Markdown doesn't offer, I break out the HTML+CSS. I cheat by using made up context-specific semantic elements so I don't have class="foo" everywhere, and the result is pretty structured and not hard for a clueful novice to understand.

It's also not that hard to move from Markdown to HTML incrementally, and generally unnecessary at all for long prose sections if you're not averse to having mixed HTML/Markdown source.

To me, RST smells very much like XML for people who don't want to admit they're writing XML. It superficially has the appearance of being "normal" plain text writing, but that illusion is fragile if you're not familiar with the language. IMO, it's akin to COBOL or SQL in that way.

dunham• 10 years ago

it can be a pain to rewrite that into rst.

If you just want to rewrite markdown into rst, "pandoc" will do the trick.

ajford3• 10 years ago

True. But that's not always all that's needed. If I decide to flesh out an API section, it would be better to put the work in and use autodoc (which of course means I have to go make sure my docstrings are up to date). Build a TOC. A lot of things in RST are not in Markdown (the whole point of this article), and would have to be added to really take advantage of RST.

chipsy• 10 years ago

When I was confronted with this dilemma for the first time I attacked it by using multiple passes. My original draft is markdown. I pandoc it to DocBook. Then I add frills and edits in DocBook.

I see the process as not being different from what's needed to do the writing - compiling notes and sketches and outlines into a coherent narrative.

vq• 10 years ago

I have a very similar process. I start of with an org document, do a couple of drafts and then pandoc to LaTeX, pull in the proper template and add the frills as you say.

al2o3cr• 10 years ago

"portable if you install all the custom extensions the document needs" is a fairly poor implementation of "portable". You might as well call the different flavors of Markdown "portable" (contra the article) since all you need to do to render them correctly is install the right parser...

nanodano• 10 years ago

This is what I think of when reading this article: https://xkcd.com/927/

=================================

Situation: There are 14 competing standards

"14?! Ridiculous! We need to develop one universal standard that covers everyone's use cases.!"

"Yeah!"

Situation: There are 15 competing standards

==========================

The argument is that there are too many variations markdowns. Their solution? Another markdown.

lutorm• 10 years ago

I feel like this drive to use a document description language that is "natural to read in ascii" but also works as a real markup language ends up fulfilling neither in practice. I prefer LaTeX than any of these half-assed markup languages that never quite works as you want.

ajford3• 10 years ago

As a former physicist and LaTeX user, I find it hilarious that you refer to any others as "half-assed markup languages that never quite works as you want". I've found myself spending way too much time recompiling my LaTeX documents to get just the look I want. And I much prefer writing my first draft in Markdown, then pandoc it to LaTeX and finish. Takes much less time in my opinion.

whyever• 10 years ago

Using pandoc markdown with inline latex works pretty well.

sotojuan• 10 years ago

Personally I love how in Elixir, documentation comments are markdown. The Elixir runtime even comes with a nice tool that generates awesome HTML from it.

For example, this:

https://github.com/parroty/extwitter/blob/master/lib/extwitt...

Becomes this:

https://hexdocs.pm/extwitter/ExTwitter.html#follow/1

patrickmay• 10 years ago

The primary limitation I've found with Markdown, and the one reason I revert to LaTeX for longer documents, is the lack of support for equations. I'd love to be able to just add LaTeX math between dollar signs.

gbax• 10 years ago

Have you looked into RMarkdown?

http://rmarkdown.rstudio.com/

Just like you said, you just use $ or $$ to add LaTeX.

I am not arguing you should write a 600 page book with RMarkdown + LaTeX (just use LaTeX in that case), but it has worked well for me for technical reports and presentation.

groovy2shoes4• 10 years ago

Pandoc supports LaTeX-style mathematical markup. (Simply an informative note, not to discourage you from using LaTeX for your documents (I do, too)).

_getify4• 10 years ago

I wrote a six book, 1100 page series in Markdown (all on github). I write all my blog posts in Markdown.

I'm sorry but I just can't sympathize with any of the complaints leveled against Markdown. They are so minor and compared to the massive adoption of the common bits of Markdown, there's no chance I'd ever choose to write anything in any other markup than that just for those small annoyances.

I don't need custom extensibility when I can just add HTML. HTML is pretty good at markup, and it enhances the markdown in those rare occasions where what's provided seems too limited. The very last thing I'd want to do is literally write code as an extension to my markup language. The only code in my markdown is inside nice tidy code blocks for display purposes only.

I also use JSON for configuration, even though many have tried to convince the community that YAML or some other format is better. I pre-process my JSON to strip it of "non standard" comments, and I'm quite happy that I chose the by-far-defacto-standard there instead of going off the beaten path.

falcolas2• 10 years ago

To your second point if you use a YAML parser, you can continue to consume and emit your JSON files and get comments for free. Plus, when you get to a use case JSON doesn't support, you can continue to use the same parser for the one-off.

_getify4• 10 years ago

YAML claims to not be markup, but it clearly is a markup for data (significant whitespace/indentation, etc). When I want to do markup, I use Markdown.

When I want to data serialization, I use JSON. It's incredibly easy to strip comments (and whitespace, for that matter) from extended JSON before transmitting and/or parsing. I wrote `JSON.minify(..)` for that years ago, and it's literally never been a problem for me since.

forsaken2• 10 years ago

Curious how you cross-referenced across the books? Did you do listings of API's?

Markdown is great for text content, not for formal documentation.

_getify4• 10 years ago

The books were intended as source material for publishing, so I didn't embed any crosslinks in the documents.

However, I always use markdown for all my OSS project documentation (READMEs, etc), and I do lots and lots of cross-referencing in that context. I use simple markdown links to named-section anchors.

It's a tiny bit more manual than I'd like, but it's never stopped me from doing technical documentation effectively.

sigsergv• 10 years ago

Markdown is fine for books, but not for technical docs.

Techdocs have lots of cross references and other similar elements, their implementation in all markdown “standards” is really bad.

ReStructured text is much, much better.

_getify4• 10 years ago

I didn't mention in my comment, but I also use Markdown for all my technical documentation (READMEs) on my dozens of github OSS projects. I have lots of cross-references and I use normal links to named section anchors (sometimes that I insert manually via HTML).

It's not perfect or even ideal, by any means, but the other benefits of Markdown are more than enough to make up for the slight annoyances here.

I don't know about ReStructured text, but I can say that none of the examples in the OP swayed me that I'm missing anything of any import.

accordionclown2• 10 years ago

markdown can indeed work "good enough" for books.

assuming you're using one of the extended flavors.

but once it comes to the repurposing of your text, switching to another flavor (for many good reasons) will cause _many_ undesirable wrinkles to appear, with a lot of them being rather difficult to find.

you might think this is a problem you'll never face. i hope, for your sake, that you are right about that.

but don't say that you weren't warned.

because the experience is unhappy, and tedious.

and not what you'd expect from a "plain-text" format.

the _idea_ for markdown (which, by the way, should be credited to ian feldman, with a follow-on by dean allen) is spot-on. but the gruber realization is short-sighted. (and, alas, stubbornly so, for absolutely no good reason.)

cyberpanther• 10 years ago

I think most the arguments made in the piece don't matter but the argument for Lack of Semantic Meaning is interesting in how Markdown solves it. First off the argument is bad because Markdown can have semantic meaning, it is just defined with HTML. So the real argument is semantic meaning in HTML sucks. In his example, I would generally agree. However, what if you just used <warning>Warn Me</warning>. I kind of like that a lot.

jwilk• 10 years ago

Is it [text](URL) or [URL](text) or (text)[URL] or...? It's impossible to remember, because this syntax is bizarre.

UnoriginalGuy• 10 years ago

I too get them back to front, but to be frank I have no better suggestion. Markdown definitely isn't perfect, but it is "good enough." Now if Only HN supported Markdown :)

r3bl• 10 years ago

Why do you think it is bizarre? I find [text](URL) pretty simple to remember.

On the other hand, creating a clickable image:

    [![alt-text](URL)](url)

...is way too complicated than it should be. In fact, I'm not sure if I wrote the syntax correctly right now.

I'll never understand why clickable images are not the standard way the image renders once you type in:

    ![alt-text](url)

optimusclimb• 10 years ago

Don't blindly follow advice from articles with hard "yes/no" imperatives as titles.

groovy2shoes4• 10 years ago

I don't have a particularly strong opinion about most markup, but I know for sure I'll never use something that uses xmlto/xsltproc as part of the toolchain (such as Docbook). As a maintainer of several packages for a Linux distribution, I've gotten far too many headaches dealing with packages that rely on Docbook for generating their manpages or other documentation. The user's xsltproc setup has to be just right for the packages to build. Anything off in the XML catalog will break the whole build. Supporting it has been the opposite of fun.

For manpages, I write mdoc directly. It's not hard. There are several great mdoc resources on http://bsd.lv

For reference material, I stick with either Pandoc or I use LaTeX (along with tex2page for generating HTML). Anything fairly small tends to get the Markdown treatment. If it's something I foresee will need to be split into multiple documents, I reach for LaTeX. Scribble is pretty nice, too, if you're dealing with Racket or Scheme.

mchahn• 10 years ago

I have been expecting github markdown to become the defacto standard just as github itself has become the defacto standard for hosting.

This would be a good thing since any standard is better than the tower of babel we have now.

talles• 10 years ago

This leads people to embed HTML directly in their Markdown

I don't find that too bad.

zmmmmm• 10 years ago

Markdown has a lot of faults, but it solves the one single biggest problem in writing documentation that basically overrides every single other consideration: getting people to actually write it. Basically nothing else matters except this.

And I disagree about the portability. Write Pandoc-compatible markdown and you can convert it to just about any format under the planet. I love that I can write in Markdown, then quickly create a word document to send around the office for comments - whatever anybody says about Word, the track changes and review functions both useful and defacto standards in most offices.

marssaxman• 10 years ago

Markdown has always seemed to me less like a file format or a formal document syntax and more like a set of strategies for upsampling plain text into such a structured format by looking for the sorts of informal conventions people naturally use when they're writing plain-text documents.

Or - I should say, it infers structure from the sorts of things people did as a matter of course back when we had a network culture based on sending each other blobs of text via email or Usenet. I'm sure the original author of Markdown.pl was not intending to design a new structured document language at all, and simply wanted to pretty-up some plain text files for display on the Web. The structure was already there, the conventions were already in common use, and Markdown.pl was just one strategy for doing something useful with them.

I think it's easy to get people to use Markdown because it doesn't feel like writing in code, and it doesn't feel like writing in code because it's basically just the sort of thing we all did all the time before the web took over.

Ironically, then, I think it actually will make Markdown less useful to build it up as a rigidly specified uniform document protocol offering sophisticated formatting features. There's certainly value in having the various makers of tools doing this job work together toward a common understanding of the patterns people like to use, but it's far less important whether someone uses triple-tickmarks for quoting or four-space-indentation for quoting or whatever, so long as the tool can recognize that they are doing something, take a reasonable guess at what that might be, and then offer a simple way to correct that guess later if the user is particularly concerned about the way the text is being rendered.

accordionclown2• 10 years ago

this is an astute comment. (because marssaxman.)

but the problems arise because different markdown flavors recognize different types of "common understanding of the patterns people like to use", so misunderstanding happens.

mastax• 10 years ago

Rust uses markdown (with some extensions) for its documentation. This has some limitations, and there was a discussion [1] about changing this to RST a while ago, but it never happened.

[1] https://internals.rust-lang.org/t/rustdoc-restructuredtext-v...

steveklabnik• 10 years ago

The only real issue I have with it is manually creating links to other things, which is tedious and error-prone. I'm hoping to transition us to CommonMark, and with it, an extension that can do this.

hobo_mark• 10 years ago

I really tried to write in ReST but there is nothing intuitive about the syntax and I kept forgetting how to do things, it also makes the plain text unnecessarily verbose and does not support simple things like combining styles (i.e. good luck if you want something be monospaced AND bold without terrible kludges).

In the end I converted to Asciidoc, it does all I need, is readable and is not as python-centric as docutils (I use the python implementation but asciidoctor is ruby and there's even a chrome extension for live preview in the browser).

mixmastamyk• 10 years ago

Rst is a bit harder to write but more powerful and extensible. To alleviate some of the syntax annoyances I created some snippets in my editor.

oliwarner• 10 years ago

Getting developers to write documentation is hard enough already.

Raising the barrier to entry to include learning complicated markup languages will chase them off completely.

I agree, it's far from perfect. But some documentation is better than none.

shawnee_• 10 years ago

Yep, I tend to agree with the author. For software documentation with complex APIs, something more robust than markdown is necessary. For the same reason that writing extensive in-line HTML+CSS markup is bad, relying too heavily on HTML as the "fallback" for styling and structuring things that markdown cannot handle is just not efficient.

Here's a quick cheat sheet... for the "why" of semantic styling your docs with something like .rst with directives makes for better overall integration.

https://github.com/indie/sphinx-deco/blob/master/sphinx_deco...

Dowwie• 10 years ago

that's like... your opinion, man

I have done just fine with md

julie1• 10 years ago

I guess markdown is nice for unstructured text.

When you think you can learn a job (technical writer) by doing it bad rather than not doing it at all, you just take bad habits.

Serious technical documentation are structured. Pictures have captions, graphs have legends... It is cumbersome, it requires more data but that is the price to communicate (wait for it) INFORMATION to other humans.

Yes, writing structured documentation that can be easily used is part of what information technologies are. Structuring information from data.

Information is still analogic at the end and rst is just a typesetting chain designed for a domain specific kind of documents called technical documentation.

I am totally biased. I love readthedocs, I love POD, man pages, ISO documentations, IETF RFC, ASM papers, all kind of scientific papers, useful instructions that can help me do my job faster by following well known practices to be consistently readable without strain. And rst for this level of requirement is less a PITA than doing it conscientiously by hand or with markdown.

But I agree, I totally love the artistic freedom of markdown for writings too. But in a Museum, or as grafitis.

We talk about documentations right? Not art? So the title is accurate.

soyiuz• 10 years ago

Markdown is a virus. The virus shows you how you don't need markup at all.

herbst• 10 years ago

Agreed. Better use docx for every type of documentation. Just embed it with base64 if thats what you need. Nothing more standard than a good ol' docx.

sqldba• 10 years ago

Wah wah. I disagree. I'm tired of seeing this in Enterprise:

* 100 page Word document. 200 page Word document. Take your pick.

* 99% of it is clearly cut and pasted from somewhere else and contains information absolutely incorrect and irrelevant to the task at hand because it was accidentally included from the last document they cut and paste from, but people are afraid to remove it.

* Someone has manually typed in a few lines into a table (oooh, so THAT'S the temporary IP address of the server which will almost certainly change at a later date!) As it's buried in the document there's no way to extract, verify, or update it. It will be listed with a bunch of other IP addresses from the prior cut and paste, and if you get a server name in there, it's probably wrong too.

* They've also handed off the effort to any Architect, probably one of the people I see sitting in Visio day in day out drawing those diagrams of how a computer connects to the network. In a VM data centre. Where it's meaningless and has no connection to reality. And where the moment it gets turned on someone will install software that connects to 20 other servers in ways that will never be described let alone in this document let alone in a diagram.

* Now, take that, cut and paste the whole thing keeping it 90% intact, call it a "Controlled Document", add in the names of some people at the front and last edit dates (where every document starts at version 0.1 and stays there for its entire lifetime), and now you've got a process manual! Hundreds of them! Thousands of them! Don't worry they were all based on whatever kind of template the business was branded with from year to year so you can kind of tell which decade they were first created.

* And they'll be dumped in shares because whatever multi-million dollar document management system was never used by users before being bought and never ever ever works. If you're lucky they might have version numbers or edit dates which don't correspond internally but get you 90% of the way to finding which one is current.

I get to see those holy manuals in Enterprise every day. You have no idea how bad it is.

Pick a third party format apart from Markdown? Are you fucking serious? Enterprise doesn't buy fucking third party software and everything is locked down so that you can't run your own. This is Windows for fuck's sake and there aren't even decent free Markdown editors for it anyway.

I write MY personal documentation in Markdown and I do it in a plain text editor. If I ever need to draw a diagram or put in a picture then I know I've fucked up and to backtrack. It's just plain text. That's what Markdown is for. "Not portable" my arse. About the only thing I wish was easier is tables. And they'd probably be ASCII tables at that.

So yeah. The argument against Markdown is bullshit.

Don’t Use Markdown for Documentation

Related Stories