Why you shouldn't use Markdown for documentation (2016) | Hacker News Reader

Why you shouldn't use Markdown for documentation (2016)

ericholscher.com

19 pointsthrowawaymath8 comments

Open articleView on HN

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

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

The author wrote "If you are considering Markdown, I hope that you also look at Asciidoctor and Sphinx. I find them to be much better toolsets for writing documentation."

These meet all of your points except that people can't transfer their previous Markdown experience for them.

FWIW, my documentation is in Sphinx.

If you want something more powerful than Markdown, have a look into Org mode (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.

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.

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.

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

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.

Reply on news.ycombinator.com