
Why you shouldn't use Markdown for documentation (2016) - throwawaymath
https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
======
abraae
Why you should use markdown:

\- it will stop your teammates from using e.g Google docs, word files

\- it can be source controlled and diffed

\- there are heaps of converters e.g markdown->HTML

\- it's so easy to remember you hardly ever need to go to reference

\- because it's so primitive it helps focus the mind on keeping your doc
simple too

\- there is so much markdown doc around that there is no cognitive
dissonance/distraction for people reading your doc- the format is familiar to
them already

\- after a while I've come to appreciate things that are primitive but widely
used - it's convenient to say"just use markdown" and cut the bike shedding off
at the pass

~~~
throwawaymath
A few of these are good arguments, but a few are not.

You're right that Markdown is very easy to remember and you don't need to
refer to documentation much (if at all). It's also very simple and encourages
document simplicity. I like Markdown for personal note keeping. And reading
Markdown is not much different from reading

But you shouldn't use Markdown just because it will stop your colleagues from
using _other_ suboptimal document stores. If you're writing documentation you
should do it the right way, which is not by offering a poor tool to curb the
use of an even worse tool. That's not a professional and scalable way to find
a robust documentation solution. That argument would hold up better for a use
case like internal documents, in my opinion.

Likewise other documentation formats suggested in the article can be source
controlled and diffed - there's no reason why you can't use reStructuredText
in this way, for example. And there are also heaps of converters for these
suggestions, but unlike Markdown their conversions to HTML will be common and
well-specified :)

------
anujsharmax
If you want something more powerful than Markdown, have a look into Org mode
([https://orgmode.org/](https://orgmode.org/)). It works great if you use
Emacs (or variants such as SpaceMacs), and you can read/write the files in any
text editor similar to Markdown.

You can write ToDos, Documentation etc. or you can even setup the whole GTD
workflow to suit you.

I think Github can show org mode files as README files as well, but please
someone correct me If I'm wrong.

------
liamkinne
While I agree with most of what is said in this article, Markdown still has
ubiquity.

And while MD doesn't have an official standard, you still have a standard,
it's just defined by whatever is rendering your MD. E.g. GitHub markdown has
well documented behaviour.

~~~
guitarbill
In late 2018, GitHub-flavoured Markdown (GFM) has basically won, and is in
tools used every day. reStructuredText has always had a learning curve, but is
even more painful if you're used to using Markdown (`foo` in MD vs ``foo`` in
reST).

I do use reStructuredText/Sphinx for Python, but it's a chore onboarding new
developers, to the point where I may not bother in future. Getting developers
to write docs is the most important - badly formatted Markdown is still better
than no docs. Lower barrier to entry wins. Eric does understand this very well
via Read the Docs/Write the Docs (which are awesome), but reStructuredText's
weirdness will always be an issue.

------
0db532a0
texinfo is the official documentation format of the GNU project. It is
standardised, ubiquitous, allows cross-referencing and version control, and
provides all the semantics you might need. It allows you to render into
multiple formats.

[https://www.gnu.org/software/texinfo/manual/texinfo/html_nod...](https://www.gnu.org/software/texinfo/manual/texinfo/html_node/index.html)

------
beatgammit
The best tool for writing documentation is the one that you enjoy using. Most
documentation is crap, and it's really not that hard to port one markup to
another (it's an hour or two of pain, but that's it).

I've tried restructured text, and it's just slightly painful enough that I
drag my feet writing docs in it. I haven't tried the other suggestions, so I
can't comment on them.

The nice thing about markdown is that it's "good enough" and ubiquitous. My
READMEs and static websites are in markdown, and many tools have markdown-
style options. Even Reddit uses markdown, which is pretty neat. Yes, the
"flavors" are mildly annoying, but they're close enough that it doesn't matter
too much.

I don't _love_ markdown or anything, by it is "good enough", so I haven't
bothered trying to replace it.

