One point that's not really touched upon is the fact that it really does matter whether the person writing the documentation is a technical writer or a developer.
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.
Completely true, until you need a feature that the less powerful format does not support. Then you are back at the beginning, regretting spending all that time learning something that won't fill your needs.
ReStructuredText is not hard. Yes, unusual features are hard to memorize, but a quick google search beats it being impossible every time.
Though this could be said for literally anything you learn how to do. I spend my time learning the tools that will give me the biggest impact most of the time, and use the easiest tools for most other things, simply dealing with their deficiencies.
I wouldn't say Markdown is simpler. It has fewer features, but the core experience is about the same as reStructuredText.
RST header markup is more readable in plain text. In Markdown, the less important a header is, the more hash marks. In RST, I am free to make less important headers have less visual weight.
Markdown also supports non-hash mark headers, similar to RST, but it is a bit tougher to deal with its h1 -> h6 progression than RST. The RST rules are clearer and standardized, whereas Markdown's are not and especially vary between engine implementations. One more area where CommonMark standardization may help some time in the future, but doesn't quite impact today.
They're standardised but I wouldn't say they're clearer as the "level" of a specific over/under symbol only depends where it first appeared in the document, I've seen projects where two documents side by side used different underline symbols for the same depths, that gets confusing.
I'd like rST/Sphinx to be stricter on this point, maybe I should open an issue/PR allowing upfront definition of the over/underline hierarchy for the project.
Agreed, RST headers are too "flexible". They're also IMO quite annoying to write and maintain (exactly matching the title length) or ugly (overlength).
Plus, solving inconsistencies with simple head math: $ to the end of lines to get the character counts from the two line and say, add 3 with 3i=[Esc] or subtract 5 with 5x. With over and under decoration you can . the other side to fixup both.
Header significance to visual weight inversion is the same deal in the lauded orgmode. In both cases, the trick is to see the hash mark weight as indentation instead of significance, or, preferably, configure your editor to weight the headers using font customization.
When working in an entity, use whatever the team is using obviously.
Otherwise, if you haven't learned any of those two and are wondering which one you should pick, it's cool, because
> You especially don't want to spend very much time learning the intricacies of a new markup format, unless you absolutely have to.
is moot anyway. Starting to write in RST is not more complicated than starting with MD. No need to learn the minute details to write basic documents. You will have plenty of time afterward to refine the thing once you're accustomed to it and feel the need to produce more advanced outputs.
As a developer, I would LOVE a tech writer to sit next to me and walk me through the best way to write documentation, using the best tools. And by "best," I don't mean what I think is best, I mean what the professional tech writer thinks is best. Until I have the experience to opine to the contrary, it is my responsibility as a software engineer with a mission to produce quality software to care deeply about documentation, even if it's not my full time responsibility. I would love to see more articles about the "how." I would learn a lot and be a better software engineer as a result.
Thanks for that, although I don't think those particular tools apply in a polyglot sense, the concepts establish a nice pattern to replicate in other tool chains.
I actually recently introduced RST and Sphinx to our documentation team of 4 non-developers, and the most difficult hurdle was actually teaching them to use git (even with GUI SourceTree). Getting multiple non-developers (2 are remote) how to install Xcode and Docker produced more confusion then I thought it would. We've finally gotten into a flow, and better documented how to install the documentation tools, and it's been working quite well.
You mean like vim, emacs, nano, kate, notepad, notepad++, wordpad, or any other plain text editor?
Really - I don't get this impulse at all. From my perspective, the entire point of markdown (and RST I assume, though I haven't used it) is that you can easily read and write it using any plain text editor.
If you are going to need a specialized editor to write it, you might as well use html, docbook, docx, odt, troff, rtf, or any of the zillion other formats.
Back to the main point, for non-developers all of those can be quite confusing especially when you're used to Word/Google docs/etc. A text-only editor where you don't get live feedback is quite an adjustment and there is a cognitive switch to the text you're writing and imagining how that text will be presented.
It's been a while since I've written rST but there were good plugins for both emacs and Sublime to boot (for e.g. filling the header under/over line or toggling between different header styles)
I don't know why this is such a common opinion. I'm reluctant to write docs exactly for the reason of not knowing the best tool for the job (or even an "ok-tool"), and I don't really have a luxury of finding it out exactly because I'm a developer and have stuff to do aside from writing docs. If I already had developed a workflow for writing docs, I assure you, writing a manual would be no different to me from writing a parser or some RPC-server or whatever. The only difference is I already have a workflow suitable to write parser, because I've written tens of them, maybe over a hundred already. I'm only thinking about the business-logic, my fingers just do the job.
On the contrary, when I'm trying to write a manual larger than a few screens, say, docs for an API with more than 20 entries, I have to think about the tools to write, compile and display the documentation in a way to be comfortable for both the developer and the user. I'm not in a mood to write my own, and the Internet recommends me to use something that requires installing whole Ruby dev-stack (and I don't use Ruby) and produces something hardly even readable. That's why using markdown + pandoc, or even google docs might be something I resort to.
If somebody would show me "The Way", spending a day or even a week to get fluent with the tooling I can use from now on would seem to me a minor nuisance, hardly even noticeable.
No way. First, it has to be hosted in house. Second, that's basically the same markdown + pandoc I use for free already. Except it's even less flexible, and costs money. If API documentation would be just an ordinary book, I wouldn't have the urge to change anything, as pandoc + custom CSS actually does fine. Generating HTML + TOC from a bunch of .md files isn't really a problem, you know, it just isn't what makes writing API docs painful. I have a couple of sentences to say about every RPC call, maybe. It's actually mostly about providing huge (so, I guess foldable) params/result examples and making it easier to change the docs when the code changes. See Slate for example. Or even readthedocs. Both are not even remotely perfect, but are wa-ay more suitable for writing docs than gitbook.
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.