Hacker News Reader

Comment by cubes | Hacker News Reader

I've used both Markdown and RST extensively. I feel RST has a steeper learning curve than Markdown, and that can be an obstacle to a successful documentation culture at an organization.

As a former colleague liked to say, "The bar to authoring documentation needs to be so low you can trip over it."

View on HN

While completely true, and I personally prefer markdown documentation (or even just a README.md if I can get away with it), larger projects definitely benefit from rst. You're probably going to end up re-inventing parts of it, like all of these markdown documentation projects do via extensions to the language, or littering your markdown with HTML like <div class="alert alert-info">Note, this feature is only available on processors with SSE2 or greater!</div>.

> As a former colleague liked to say, "The bar to authoring documentation needs to be so low you can trip over it."

Wikis have an incredibly low bar, and at some point making things easy leads directly to garbage-in-garbage-out disorganization.

Having docs go through the same linting and code review process (which should also be easy!) as code is the way forward for docs longer than a few pages.

Sphinx is excellent and batteries included for this sort of lint process.

The learning curve for RST is generally higher because it does more. You'll notice that Markdown's learning curve goes up quite a bit as they add all the features that RST has. That said, RST has some bad design decisions, but I'd say about 75% of the complexity it introduces is needed, and the 25% is bad design.

If you have to extend Markdown, the battle is lost. The basic core idea, is OK, but as soon as you find yourself needing to do more documenty things (lists with formatting, tables, etc.) its the wild, wild west - different extension standards CommonMark, Github style, etc., editor, or library of choice.

Not to mention all the special-custom-component standards now which require code... the whole point of Markdown was you could just use any old text editor and be just as well off as looking at a prettified version.

You have the higher complexity and learning curve anyways, more, even.

I guess, the bad design decisions in RST are bad, but there are equally bad design decisions in all these new extensions, editors.

Instead of trying use a hammer put in screws, we should just change tooling. If you need document-level formatting etc., plain-text formatting is cool but don't try to be markdown. Use markdown when you just need simple text docs, if you find yourself doing complex stuff maybe you shouldn't be using markdown, or at least not calling yourself "markdown".

Reply on news.ycombinator.com