Hacker News Reader

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.

That's true. What makes this case special is that there's almost no change in difficulty between the more and the less powerful tools.

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.

> The RST rules are clearer and standardized

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).

rst-mode in Emacs does wonders in this respect.

This is a long header.[esc]yypVr=

Came here to say this.

Gesundheit

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.

I've tried to do this in the past, but there hasn't been much interest at large. I presented this article as a workshop in santa cruz python meetup earlier this year, https://jeffquast.com/post/technical_writing_with_sphinx/

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.

The GNU Coding Standards document has some advice on exactly this:

https://www.gnu.org/prep/standards/standards.html#GNU-Manual...

I totally agree.

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.

Also, there are a bunch of editors for writing Markdown for most platforms and few (any?) for ReStructuredText.

IDEA-based IDEs has a nice support for reStructuredText, I use this PyCharm feature almost daily.

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.

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)

You certainly don't need editor support, but even for a format this simple there are still things an editor can do to make it more pleasant.

At a minimum, I want support for:

- Key bindings

- Syntax coloring

- Toggle preview within the editor

I found Markdown generally had much wider support than RST.

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.

Online: http://rst.ninjs.org/

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.

Use Gitbook. It kicks all kinds of ass, is easy, and has online editor, offline editor, and cli toolchain if needed.

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.