
Don’t Use Markdown for Documentation (2016) - yinso
http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
======
chipotle_coyote
Articles like this come up every so often, and they usually point to all the
problems with Markdown -- slightly incompatible implementations, nonstandard
extensions, how difficult it is to correctly parse in all cases, how mixing
non-tag markup and HTML offends proper sensibilities, etc. And I can't say
that they're _wrong,_ per se. Markdown is a terrific example of "worse is
better."

That's the thing, though -- the whole argument for "worse is better" is that
it produces more successful software. In practice, it turns out that it's
pretty easy for most people to write most things in Markdown, no matter which
processor they're using, just merrily mixing in HTML (or template tags) when
they need to. The arguments for AsciiDoc and ReStructuredText usually boil
down to "they make difficult things easier," which they do -- but they tend to
make more _common_ things (links, images, blockquotes, footnotes [not
technically "standard" Markdown but the [^fn] notation is nearly universal]) a
little more difficult. Markdown, by contrast, makes the things you're typing
_all the time_ trivial, while still letting you do anything that you can do in
HTML by, well, letting you do it in HTML.

------
jitl
The litany of issues about Markdown flavors and interop issues there doesn’t
ring true to me: most tools these days use Github-flavored Markdown. Never had
a parsing problem between the various Ruby, Python, and C markdown libs I’ve
used over the years.

Getting engineers to contribute to docs is hard enough; it’d be quite a
barrier in my org to also teach them a new markup language. Everyone already
knows Markdown or some subset of HTML.

------
h3rald
While I understand the point that the article is trying to make, i.e. that no
"standard" markdown offers sufficient features to write documentation, I don't
think that it matters too much as long as the final result is good.

I always wanted to write manuals and documentation in markdown (or any other
lightweight markup language for the matter) but not even a specialized flavor
of markdown was able to provide all the features that a technical writer
expects from a documentation tools (I am talking especially about block-level
formatting and content reuse).

So I came up with HastyScribe
([https://h3rald.com/hastyscribe/](https://h3rald.com/hastyscribe/)) and then
HastySite ([https://h3rald.com/hastysite/](https://h3rald.com/hastysite/)).

Basically, I used Discount as a base and added features on top of it. I am now
using it for all my sites and all the documentation of my open source
projects. And I know of at least one company that is using HastyScribe for
their own user documentation.

OK, there's some degree of vendor lock-in, but at least the final result is OK
and both tools are open source.

For more info and a preview of what an HastyScribe document looks like, here's
the user guide:

[https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm](https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm)

------
paulcole
Since most people commenting will do so without even opening, let alone
reading, the linked article, let me draw your attention to the last line:

>Full Disclosure: I work on a product, Read the Docs, which is based on
Sphinx, so my views are likely biased.

------
ChicagoDave
If I can anyone to actually write documentation, I don’t care what tool they
use as long as it’s a reasonably accepted tool.

Any flavor of markdown qualifies.

------
rlabrecque
What we ended up doing was just reusing our existing bbcode support. Markdown
wasn't giving us anything over it really and it was easier to reason with,
especially for non-technical folks and translators. We were able to extend it
for our use cases much easier.

All of this after the initial plan was to use Markdown.

------
nixpulvis
Rust seems to disagree, and I'm glad of it. Documentation is easy to write,
and reasonably extensible. Sure there are things I wish to see added (LaTeX
math mode would be awesome) but there's nothing really stopping this from
happening, even if it's not part of a universal standard.

~~~
Azareus
That reminds me, pandoc offers compilation of latex fragments inside markdown
source when exporting to pdf, which is how I typeset almost all of my math.

This is of course not even close to the same thing as official support would
be, but it's good to have in a pinch, so you can typeset some math without
having to bust out a latex toolchain you might not have used for a long time.

PS: pandoc offers a command-line flag to set the latex engine, which means you
can use XeTeX or LuaTeX for better unicode support.

------
tgp
Markdown is fine for small snippets, READMEs, Github comments etc., but I
don't think it's suitable for a longer document such as software
documentation. After thinking about that problem and exploring options for a
while I have come to believe that some lightweight markup that can be
converted to DocBook may be the way to go. I have blogged about such a
pipeline here: [https://nablux.net/tgp/weblog/2017/04/02/lightweight-
semanti...](https://nablux.net/tgp/weblog/2017/04/02/lightweight-semantic-
markup/)

------
fnayr
Thanks for the alternate suggestions (biased as they may be).

My biggest pain point when writing doc in md is tables. They are so hard to
parse in the raw text, and I constantly have to be checking the rendered
output to make any edits/find my place.

Does anyone know of a good alternative to md (including Sphinx and
Asciidoctor) that deals with tables better?

~~~
jitl
I use HTML <table> in my markdown. Works great. Many already know the syntax.
Supports large table cell bodies in a readable manner.

The downside is the syntax is noisy compared to your average markdown, and the
tables don’t make much sense in text view.

~~~
fnayr
Ah yes I hadn't really thought about that for some reason. Do you view HTML as
something that should only be used where necessary in MD or just go crazy with
it?

~~~
jitl
I use it when it’s needed:

1\. Tables

2\. Collapsable sections with <detail>

3\. Color-coding with <span style=“...”> or <span class=“...”>

------
dang
Discussed at the time:
[https://news.ycombinator.com/item?id=11292280](https://news.ycombinator.com/item?id=11292280).

------
firegrind
The alternatives mention python and ruby. What drew me to markdown in the
first place was the absence of dependencies.

------
gcb0
only if github offered sphinx support.

~~~
yorwba
They do, unless there's more to Sphinx than just reStructuredText?

See the list of supported markups here:
[https://github.com/github/markup/blob/master/README.md#marku...](https://github.com/github/markup/blob/master/README.md#markups)

~~~
dozzie
Plugins, like autodoc.

