Why You Shouldn’t Use “Markdown” for Documentation (2016)

alpaca128 · 2023-10-06T08:58:35

The inconsistencies between Markdown implementations are annoying, but in my experience it's rarely an actual problem. Most seem to aim for Github's flavor with maybe one or two deviations, which seems to be the closest Markdown ever had to a standard. Whenever I try a note-taking or messaging app I just go in with that assumption and it usually just works.

Also let's not pretend other formats have necessarily more consistent or complete implementations. Sure, Github supports 9 different markup formats, but go try using .org files in anything but Emacs and you will always be disappointed. Some implementations can't even render checkboxes and pandoc is very inconsistent as well, not to mention a complete implementation would also need to fully support LaTeX.

> for any reasonably sized set of docs you’ll need things that aren’t in the basic language.

Any examples of features that aren't supported by Github Markdown?

> With other markup languages, you can extend the language to provide the features that you need.

Markdown can be mixed with HTML. Not ideal but very flexible.

WolfOliver · 2023-10-06T09:56:13

I do not have a problem with the inconsistencies between implementations, this is indeed not really an issue. But what I do not like:

- Inserting a link is confusing, is it [url](text), (url)[text], [text](url), or (text)[url]

- Tables are a pain

- Footnotes are a pain

- Cross referencing headings are a pain

- Bold, italic, underline are the only features that are simple to use, but I do not need it that much

- No other things than the ones which are a pain or I do not use very often are not possible at all (image captions, table of content, ...)

Of course you can say you can use a proper editor, but then I could as well use a WYSIWYG solution

rubella19 · 2023-10-06T09:07:20

Thanks! Your comment encouraged me open GitHub Documentation on Documentation (https://docs.github.com/en/get-started/writing-on-github/get...) and in BASIC section there are way more than I imagined.

jjgreen · 2023-10-06T09:32:05

Agreed, the main advantage of Markdown is it's easy, so encourages quick ephemeral notes which would otherwise be plain text, and if done properly (i.e., written as plain text with some extra conventions) is readable as plain text, and you get a pretty view on GitWhatever.

If you want big formal documentation, are you sure? It has less value than you think and imposes a maintenance burden which will eat your life. If yes, then use DocBook or LaTeX.