
ReStructuredText vs. Markdown for technical documentation - nikbackm
http://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/
======
StefanKarpinski
A big difference between ReST and Markdown is that it's very easy to
accidentally write ReST that is either invalid or doesn't mean what you think
it means. The Julia manual used to be written in ReST and even people (or
maybe especially people) who were pretty deep down the ReST features
rabbithole, regularly committed ReST that was just wrong – quotes where code
was intended; incorrect hyperlinks (why is the hyperlink format in ReST so
damned complicated and non-uniform – it's basically impossible to remember);
bullets or lists that aren't actually bullets or lists. This is possible in
Markdown, but it's much harder: by design, things almost always mean what they
look like they mean. That's a huge benefit. The Julia docs are now in Markdown
and accidentally broken markup is hardly ever a problem anymore.

~~~
1wd
I agree that ReST is needlessly complicated. But Markdown isn't really that
much better. Maybe it's because I'm more used to Wikipedia-style link syntax.
As for bullets: Since some Markdown implementations annoyingly insist on four
spaces, while others work fine without that, I'd say it's about even.

But these are all minor annoying details of either. The win of ReST is
standardized extensions for anything. The win of Markdown is there's half an
implementation running anywhere.

------
type0
Neither is any good for technical docs, Asciidoc/Asciidoctor is by far the
best. You get automatic numbering, conditional includes i.e you can pull in
specific pieces of code into your docs when you tag them. Look it up, it's
extremely powerful and as easy to write as reST if not easier because it's
more consistent.

~~~
david38
I just read some articles on why Linux went from asciidoc to RST. Interesting
read.

~~~
type0
I guess you meant this -
[https://lwn.net/Articles/692704/](https://lwn.net/Articles/692704/)

"When comparing the markup formats for the purposes of kernel documentation,
only the table support, which is much needed for the media subsystem
documentation in particular, was clearly identified as being superior in
AsciiDoc. Otherwise, the markup comparison was rather dispassionate; it really
boiled down to the tools themselves...

... In the kernel tree, there are no tools written in Ruby, but there are
plenty of tools written in Python. It was fairly easy to lean towards Sphinx
in this regard."

As I read it, Asciidoctor is still superior, but their decision was to go with
something written in Python that they could adapt for these specific needs.

------
linsomniac
I really want to love ReST. Part of that is that I like writing in text but
having it look good. Part of it is non-technical; I've known the ReST
developer forever. And if you need to do something complex, ReST is definitely
the way to go.

If I was writing a technical book, I'd probably use ReST.

But, 99.9% of the time, my needs are much more mundane and fit well within the
limitations of Markdown. Usually I can just sit down and write Markdown,
sometimes I need to bring up a cheatsheet. When I just need to add some
documentation related to my work, Markdown is perfect.

What I'd really like is something where I can write Markdown, but if I run
into needing something it can't do then switch over to ReST. Because of the
overlap, that seems like it should be doable. I was looking at some static
site generators that might do that, but I had limited time to evaluate them
and couldn't get my existing ReST documents directly to render there so I had
to get back to work.

If anyone has had any success with that, I'd love to hear about it.

Oh, that and a way to see the results without having to render and load the
results (which currently involves mercurial, fabric, sphinx, and a browser for
me). I don't need WYSIWIG, but a quick render would be nice.

~~~
timClicks
If you're writing a book, I would strongly recommend Asciidoc syntax and the
Asciidoctor toolchain.

~~~
linsomniac
Thanks, I'll take a look, even though I have no plans of a book. :-)

------
breadbox
Good article, but I couldn't help stumbling over the thumbnail history of
markup languages in the introduction -- in particular the assertion that
Markdown, "in 2004 ... really pushed the concept over the brink of
ubiquitousness". I would say that the concept of markup languages truly became
ubiquitous in the 1990s, with the extremely widespread popularity of a markup
language that the author didn't even mention -- the Hypertext Markup Language.

~~~
eliben
That history was supposed to cover _lightweight_ markup languages like MD.
Otherwise of course the history goes way back :)

------
Mikhail_Edoshin
I use reST daily agree that reST itself a bit too complicated; it would be
much better to have a conceptually simpler syntax, closer to that of Markdown.
Also, some of their syntax choices look too artificial for a plain text
format.

Yet for me reST is a clear winner, because it's extensible; it's relatively
easy to a) write your own directives, substitution directives, and text roles
and b) hook into the parser. For example, in my workflow I only use their
parser with a few of my own extensions and only to get the parsed text as XML;
once I got this, I continue with XSLT to transform it into what I need. (I use
Python and lxml with my own extensions to XSLT as well, so I can, for example,
manipulate files and update a whole directory tree right from XSLT.)

I think most of these tools would benefit if their parser was a separate
component that could save the resulting tree into XML. (It would be ideal to
have a configurable parser where you can tinker with the grammar.)

------
marcinkuzminski
Interesting article, i had the same thoughts on MD vs RST when building
commenting on RhodeCode. That's why it supports both, and i find it the most
flexible solution

------
stevejohnson
I took a shot at using Markdown for a docutils/Sphinx "competitor" just to see
if it could be done. My solution for extensions that don't require parser
modifications was just to use custom HTML tags. Existing parsers know how to
deal with those!

As soon as I finished it, I quickly realized that lobbying for its adoption
and supporting it would be painful, but you might find it interesting.

[http://steveasleep.com/computerwords](http://steveasleep.com/computerwords)

------
chipotle_coyote
While it's technically correct that Markdown has a mishmash of implementations
(and technically correct is the best kind of correct, after all), it's worth
pointing out that MultiMarkdown has both a well-defined feature set that
includes things like tables, footnotes, and citations, a standard way to
express metadata, and has a reference implementation in C.

[http://fletcherpenney.net/multimarkdown/](http://fletcherpenney.net/multimarkdown/)

And, you might say, "But I've never heard of MultiMarkdown," but the reality
is that if you've used Markdown for creating, well, tables, footnotes or
citations, or used a YAML metadata block for a Jekyll blog, or any number of
things that weren't in the original Markdown spec but that people in practice
do all the time, then you've used something that was either influenced by
MultiMarkdown or something that MultiMarkdown adapted.

And that last point is larger than MultiMarkdown, specifically. I'd argue that
Markdown _as commonly implemented and used_ can do an awful lot of things that
are necessary for technical documentation work. This isn't to say that ReST or
AsciiDoc aren't more powerful, but in practice, there's very little I've had
to write that can't be written in (Multi)Markdown.

------
SteveLAnderson
If by technical documentation you mean a readme page, or a few internal pages,
then either are fine, as are AsciiDoc, org, etc. There's no huge advantage or
disadvantage to any of them; use the one that is easiest for you to write in
without having to look up cheatsheets.

A lightweight markup language is designed to for the user to quickly write
something, and most of them have been designed with the goal of having
programmers document their work without having to learn a complicated tool. If
you need to write extensions for a lightweight markup language, you're using
it wrong.

For anything more than that, I'd use something designed for technical
documentation (DITA and DocBook come to mind).

Lightweight markup languages seem easy, and, in the beginning they are, but
over time, as revisions pile up and more people work on it and you find you
have more requirements than you thought you had, they become a huge hassle.
You spend more time fiddling than writing. There's a reason professional
writers tend to use richer tools - they make their jobs easier and they make
the result better.

------
mjevans
I find that markdown is good for 'simple' human readable things, but that
parsers can often fall on their faces.

A particular issue I have with markdown is the bold/italic issue. However this
is probably indicative of a broader issue. Markdown either does not have, or
does not commonly make users aware of, an escape character which will always
invoke a control-word boundary and which will never be rendered in the final
text.

I've also often had different websites variations on features fail when they
are nested (sometimes at all).

------
daly
Latex...(drops the mike)

~~~
marcinkuzminski
imho latex is too complex, it's hard to sell on this when introducing it to
organization.

------
jitl
You're not gonna show me the syntax? Or how easy it is to extend?

¯\\_(ツ)_/¯

~~~
dochtman
This is not a Markdown or reStructuredText tutorial, it's a comparison on some
higher-level technical grounds. It's pretty easy to find syntax examples for
both Markdown and reStructuredText, and very simple googling will lead to
docutils documentation on extending reST.

