ReStructuredText vs. Markdown for documentation

If you're a tech writer, you're probably interested in using the best tool for the job, because writing documentation is what you do day in, day out. If ReStructuredText is the most powerful format, then you're going to strongly lean toward that.

If you're a developer, however, writing documentation -- while you may recognize its necessity -- is a task that is often a slog. It's something you do so you can get it out of the way, and you really don't want to spend very much time thinking about the "how." You especially don't want to spend very much time learning the intricacies of a new markup format, unless you absolutely have to.

I say this as a developer who is also a writer. I enjoy writing, but I know many developers don't. And if Markdown makes it easier for them to write documentation, either because they're already familiar with it or because it's just a simpler format, then I'm all for it, even if ReStructuredText might be a bit powerful overall.

I prefer Markdown.

It's readable and easy to start writing by non-technical folk. More than that that, it's less flexible and isn't as likely to be destructive. At the end of the day rST is as complicated and as flexible as something like HTML. The biggest problem is its ability to nest markup. Markdown is pretty flat and you're not putting lists within tables within blockquotes. As someone making a theme, it was pretty difficult to style against the level of nesting that people end up using rST for. This is of course me bitching about how people write their rST, but there it is. I think rST by nature leads to inconsistent markup.

Basically what I'm saying is. At that point, I'd rather just write HTML. rST sits in some weird middle world where it can get very verbose, but you end up losing all the simplicity that you wanted in the first place.

Also want to note that rST doesn't HAVE to be so complicated. Plenty of people write clean, rST docs. However, as someone who spent a good deal of time learning the Sphinx system and the markup quirks of rST, in general I ended up seeing people use it in all sorts of crazy ways which then led to weird styling errors.

When it came time to document my own projects, I just built a simple markdown system with a tree structure and added some syntax highlighting. That's gonna get most projects 95% of the way there. While you can do a lot more with rST and it is really powerful, I really think it's only for those 5% of projects or more than likely, scientific documentation that needs more context.

And from my comment in that thread:

After having written a fairly popular 400+ page book, and dozens of documentation sets in Markdown (and having worked on a few in other languages), I have to say—Markdown is _good enough_.

It will take an order-of-magnitude difference to unseat Markdown as the 'simple plain text formatting syntax' default, IMO. But use what makes you productive and is most conducive to writing effortlessly!

http://asciidoc.org

To me, this is like watching intense baseball fans argue who was better, Babe Ruth or Joe Dimaggio - neither one of them is going to play again.

1. Do you want to write something that MD is sufficient for? Write MD.

2. Do you want to write something that you need RST for?

2a. Is your document already in RST or is there no document? Write RST.

2b. Is your document in MD? Pandoc to RST. Pretty print. Write RST.

The reason this is useful is that the 90% use-case is probably hit by MD. You may never need RST. And you won't spend more time deciding and discussing than actually doing because this algorithm only takes a few seconds to execute.

The (only) good thing about Markdown is it's (allegedly) simple. IMO it's on the one hand not simple enough (e.g. HTML has got to go) and on the other hand it's too simplistic.

Ideally I would like to have a tiny core specification with a clean and simple standardized mechanism for extensions like roles and directives. With a bunch of standardized but optional extensions. Only the most important features (90% of usage) should get special syntax (bold, bullet lists, titles, roles, directives). For everything else (90% of features) there should be a named role or directive.

Trac actually uses a similar system. linkExtensionName:content, [[extensionName(content)]] or {{{#!extensionName multiline-content }}} is all you need to remember. Could be simplified a bit, but it's quite usable.

https://github.com/rtfd/recommonmark

However, commonmark currently lack support for tables, so I fall back on rst for tables(actually I think the syntax for tables in rst is much better than tables in other markdown flavors).

Also, resolving links using commonmark in sphinx is a mess, right now. I actually extended recommonmark so sphinx will properly resolve cross references(including reference to elements in a domain). However, I had to update sphinx as well, which I have a PR open with no response from them, here:

https://github.com/sphinx-doc/sphinx/pull/2644

It seems unfortunate that sphinx devs are unresponsive to contributions. The devs for mkdocs are a lot more responsive, but seem more interested in monetary contributions, unfortunately.

    A <----- B -----\
                    |
                    V
                    C

I find ReST incredibly awkward to use, really, because it's anything but intuitive - both Textile and Markdown are easier to write off the cuff.

More importantly, though, I really wish that Textile, Markdown, ReST, etc., were formally specified as PEG grammars or similar. There's just too much variation, and "standards" or specs defining them tend to be written in ambiguous English rather than something that could be formally validated and easily ported across to new languages (rather than the spaghetti messes of regexps that most parsers turn out to be when you look at the source).

We have Unicode but most of its symbols are a pain to generate on conventional keyboards.

We have touch-screens but desktop computer keyboards don’t offer them and software on phones/pads still tries a bit too hard to emulate a conventional keyboard layout.

Imagine if all standard keyboards had touch displays on the side to quickly flip between tables of related symbols, optionally with some context-sensitive mode? Then, instead of having to use creative ASCII tricks to make it “simple” to describe what you want, you just do it through your input device.

Ultimately I think markup languages will have to distill their features down to a few structural elements, and rely on Unicode (and easier Unicode input methods) to handle what is currently being done with ASCII hacks.

Let authors use the fucking tools they know and prefer.

Organise common text through translation tools. Pandoc is fucking amazing.

Formatting for final production is a separate task.

(Not without some irony, I'm reviewing a set of guides and commentaries on productivity and creativity in a few other tabs....).

When you are writing your most important task is to capture the gist of what's in your head onto a tangible medium. If that means fucking Messinian marble and diamond chisels, so be it.

The marginal productivity gains for someone already proficient in a tool are low in switching to something else, relative to domain knowledge.

The challenge is that you're then stuck with high-level, vs. low-level definitions and tools. Which is where the whole "what do I use for creating my documents" question ends up at.

Systems such as HTML5 (the semantic elements, not all the canvas and DRM crap), or LaTeX, or DocBook, are hugely useful here because their definitions are largely semantic. You write the structure, not the style.

After that, so long as a tool or language can produce ingestible input given an author's output, that's fine.

And, frankly, by the time you're worried about specific low-level structure, use a dedicated tool which provides that. My experience with LaTeX was that it was actually _amazingly_ simple to use for basic creation -- it gets out of the way. Paragraphs as linefeeds, rather than HTML's incessent <p> </p> pairs, helps immensely. For more complex structures, you can go back and add what's needed later.

Markdown offers a wide set of capabilities with the option of fallback to HTML, which again is powerful and a good option for composing.

And there's value in simplicity.

I've come to rue this decision in some ways. I like what I've been able to accomplish, but I've found most customization of default Sphinx and docutils behavior to be torture. I don't mean to drag contributors to those projects through the mud--they work well if you can just write documentation without fiddling much.

It's a Python package that allows you to extend markdown through pandoc filters. It allows you to easily manipulate the AST created by Pandoc to add any number of features.

For instance, I wrote my dissertation in Markdown , and used this to include algorithms, CSV tables, include directives, etc.

As I started writing the documentation though, Markdown's drawbacks became more apparent. Especially as the software I'm making is multi-platform and there are features that exist in one platform and not the other and I'd like to include/exclude documentation of those features based on platform, and the fact that I'd like the documentation for each platform to contain images from the program running on that platform, and so on, and this is not something that Markdown handles well.

And so I switched to ReStructuredText. RST is not as clean or as simple to write compared to Markdown, however if you are producing documentation then it is much more flexible. I can live with less clean syntax in order to get the flexibility to do what I need to do.

Hacker news, tumblr, reddit, github all do it. Honestly, if it didn't look fine in the editor and then throw an apeshit fit when posted, it wouldn't be that frustrating. But I'm so damn tired of hitting "preview" or editing my posts after posting because of misleading previews and text boxes.

In both, it is difficult to have a block of code with one line in bold, or italicized for emphasis. (The same seems to hold for asciidoc.)

Which is why I eventually gravitate back to HTML. (See https://github.com/oreillymedia/HTMLBook as well - full disclosure: I have done writing for O'Reilly.)

I wrote a number of documents in FrameMaker back in the 90s and I loved it. I really wish I had something like it now.

[0] http://rst2pdf.ralsina.me/stories/index.html