
Don’t Use Markdown for Documentation - forsaken
http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
======
geerlingguy
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.

~~~
kazinator
I wrote a 400+ man page in troff!

[http://nongnu.org/txr/txr-manpage.pdf](http://nongnu.org/txr/txr-manpage.pdf)

Welcome to the BDSM club.

Big Document in Shitty Markup.

:)

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

~~~
kazinator
I use GNU troff (Groff) for maintaining this.

And by the way, this is actually installed as a man page on target systems.

Most of my struggles were in the area of halfway decent HTML conversion. To
that end, I started with a very hacky C program calld man2html, which actually
contains a mini-troff implementation, and improved it quite a bit. I cloned
that program here:

[http://www.kylheku.com/cgit/man/log/](http://www.kylheku.com/cgit/man/log/)

This had numerous issues, among the main ones being not handling loops and
conditionals and so on for complex macros.

I still do quite a bit of post-processing on the output of this program,
still, to do things like re-arrange its order, add internal hyper-links, and
create a Java-scripted table of contents:

[http://www.nongnu.org/txr/txr-manpage.html](http://www.nongnu.org/txr/txr-
manpage.html)

(Almost the same URL as before, s/pdf/html/).

That post-processing is done by:

[http://www.kylheku.com/cgit/txr/tree/genman.txr](http://www.kylheku.com/cgit/txr/tree/genman.txr)

I don't like the approaches you have to take in troff for defining multiple
ways of doing the same thing, based on whether it is juxtaposed to something
else or followed by whitespace. This is fundamentally broken.

For instance if you want foobar such that foo is italic, but bar is regular,
you have to use .IR foo bar, rather than the .I macro. I'm sorry, but a markup
language should have the scoping/delimiting wherewithal not to have to do
stupid things like this.

I have a more or less fixed (non-growing) set of such redundant macros in the
document and so it doesn't bother me that much any more.

~~~
groovy2shoes
mandoc works great for producing HTML and PDF output from man(7) and mdoc(7):
[http://mdocml.bsd.lv/](http://mdocml.bsd.lv/)

> I'm sorry, but a markup language should have the scoping/delimiting
> wherewithal not to have to do stupid things like this.

(btw, mdoc has this and is widely supported, having been around for about 2
decades... having discovered it, I'll never write a manpage in man again)

~~~
kazinator
This "mandoc" naming of a project that was previously called "mdocml" is
terribly confusing.

"mandoc" is the name of a newer troff/nroff macro package for writing man
pages which replaced one called "man". (nroff -man versus nroff -mandoc).

The renamed "mandoc" project provides a processor which understands a "mdoc"
language, a set of macros used on BSD Unixes. It's not a full processor for
the roff language. The mdoc language has macros that resemble mandoc, like
.SH, .TH and others.

In the TXR man-page-like reference manual, I'm using real roff macros (some of
which output mandoc macros as their target, in the original sense of mandoc).

I don't think these macros could run in under the mandoc system, where you
have to use a canned repertoire of macros.

For instance, I have a macro like this.

    
    
       .coNP Functions @, boundp @, fboundp and @ mboundp
    

This parses its arguments. Any word preceded by @, is typeset in a typewriter
font, immediately followed by a comma. A word preceded by @ is typeset
typewriter, not followed by a comma. Other material is in the regular font.

Another complicated thing:

    
    
       .mets (replace-list < list < item-sequence >> [ from <> [ to ]])
    

IN this syntax "< word" means typeset word as a meta-identifier. "<< word1
word2" means, typeset word as a meta-identifier, immediately juxtaposed with
word2 (no whitespace) which is ordinary. >> word1 word2 reverses the
relationship, and <> w1 w2 w3 means w1 and w2 are ordinary , surrounding meta-
syntax w2 without space.

When you render this with a man reader, the macro puts out angle-bracket
notation, exactly like this:

    
    
       (replace-list <list> <item-sequence> [<from> [<to>]])
    

in the paragraphs which describe this, this notation is consistently used. In
HTML and PDF output, these angle-bracket notation is replaced by italics.

~~~
groovy2shoes
Ah, I didn't realize you were making full use of roff. I don't think mandoc
(mdocml) supports that; you're correct in saying that it's a canned version of
man/mdoc.

It has served me well, though :)

------
zmmmmm
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
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.

~~~
accordionclown
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.

------
danielvf
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
> 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.

~~~
danielvf
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.

~~~
forsaken
You can do code blocks::

    
    
       like this
    

:)

~~~
danielvf
Yeah - this always trips me up too, since it's two colons, not the holy Python
single colon, and it's "magic" on the preceding paragraph, not the code
itself. Django docs written in RST avoid doing this style.

You can do anything you need to in RST, but there's just more friction
involved.

~~~
cname
It's not a Python thing, though. It's a reStructuredText thing. I don't see
how this syntax is more "magic" than, say, using # in Markdown to indicate a
heading.

The reason it's a double colon is because a single colon acts like a normal
single colon (i.e., it's not interpreted in any way), which is sometimes what
you want (i.e., not every indented block is a code block).

------
_getify
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.

~~~
sigsergv
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.

~~~
_getify
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.

------
ajford
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.

~~~
chipsy
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
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.

------
102030485868
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...](https://internals.rust-lang.org/t/rustdoc-
restructuredtext-vs-markdown/356)

------
parenthephobia
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.

------
sotojuan
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...](https://github.com/parroty/extwitter/blob/master/lib/extwitter.ex#L742)

Becomes this:

[https://hexdocs.pm/extwitter/ExTwitter.html#follow/1](https://hexdocs.pm/extwitter/ExTwitter.html#follow/1)

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

Wouldn't that be HTML? :)

------
peatmoss
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.

------
groovy2shoes
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](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.

------
shawnee_
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...](https://github.com/indie/sphinx-
deco/blob/master/sphinx_deco.rst)

------
oliwarner
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.

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

------
lutorm
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.

~~~
ajford
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
Using pandoc markdown with inline latex works pretty well.

------
hobo_mark
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).

------
cyberpanther
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.

------
julie1
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.

------
herbst
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.

------
tirus
And then there's CommonMark: [http://commonmark.org/](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.

~~~
cryptos
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.

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

------
patrickmay
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
Have you looked into RMarkdown?

[http://rmarkdown.rstudio.com/](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.

------
mastax
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...](https://internals.rust-lang.org/t/rustdoc-
restructuredtext-vs-markdown/356)

~~~
steveklabnik
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.

------
al2o3cr
"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...

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

------
mchahn
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.

------
mixmastamyk
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.

------
3327
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.

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

~~~
UnoriginalGuy
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 :)

------
talles
> This leads people to embed HTML directly in their Markdown

I don't find that too bad.

------
Dowwie
that's like... your opinion, man

I have done just fine with md

------
sqldba
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.

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

------
nanodano
This is what I think of when reading this article:
[https://xkcd.com/927/](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.

