4 ms·

Good for people who like to work with non-standard markdown. Not sure why companies do not use RestructuredText (rst), which is a proper specification [0] and h

Good for people who like to work with non-standard markdown. Not sure why companies do not use RestructuredText (rst), which is a proper specification [0] and has been very successful in the area of documentation. In order to generate a print quality documentation from this markdoc format will be a huge task. RestructuredText already has strong support for Latex output. Now people have plain markdown, gitbook and now markdoc with its own set of non standard extensions. Hopefully rst format can catch up among JavaScript developers. So far haven’t seen a complete documentation tool like Python Sphinx [1]. [0] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html https://docutils.sourceforge.io/docs/ref/rst/restructuredtex... [1] https://www.sphinx-doc.org/en/master/ https://www.sphinx-doc.org/en/master/

cubes 4y ago
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."
- TkTech 4y ago
  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>.
- ericholscher 4y ago
  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.
  - smaudet 4y ago
    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".
- zdw 4y ago
  > 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.
IshKebab 4y ago
I've used RestructuredText quite extensively (my company uses it). I can see why people do not want to use it. 1. The specification for the syntax is decent but not really comprehensive. There's zero chance you could write a compatible implementation from it. To be fair this is true for the original Markdown but I think there's been a lot of effort to make fully defined versions (e.g. CommonMark), but... 2. The only implementation is the Python one. Frankly Python sucks. The Docutils code has no type annotations so good luck reading it, which you will have to do because... 3. The actual Docutils API is very badly documented. This is easily the biggest flaw. I have implemented a couple of custom directives for my company's docs and it was extremely frustrating to get it working. Pretty much down to using grep.app to search for examples of other random people that have figured it out. So I would strongly recommend not using RST. I've been wondering what would be better for a while - normal Markdown is just not rich enough for good docs. This looks pretty nice though. Latex output is nice, but not really super important in 2022 and definitely not worth the flaws of RestructuredText. Do not use RestructuredText.
- euroderf 4y ago
  Several previous discussions at HN have suggested that AsciiDoc is better to work with than RST.
- __mharrison__ 4y ago
  Funny you say that. I spent most of last week porting some of my rst based book authoring tooling to md/pandoc.
__mharrison__ 4y ago
At this point using rst is like advocating for Subversion instead of Git(hub). (Which is actually a good metaphor considering where docutils is hosted...) I say this as a (former) committer to docutils. The LaTeX support is ok in rst if you want to create something similar to a Word document. If you actually wanted to print a book, you need to use something like my tool, rst2nitrile. The Python documentation folks seem to be interested in abstracting Sphinx to markdown as well with MyST... rst is a dead end at this point.

cubes 4y ago

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

TkTech 4y ago
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>.
ericholscher 4y ago
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.
- smaudet 4y ago
  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".
zdw 4y ago
> 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.

IshKebab 4y ago

I've used RestructuredText quite extensively (my company uses it). I can see why people do not want to use it. 1. The specification for the syntax is decent but not really comprehensive. There's zero chance you could write a compatible implementation from it. To be fair this is true for the original Markdown but I think there's been a lot of effort to make fully defined versions (e.g. CommonMark), but... 2. The only implementation is the Python one. Frankly Python sucks. The Docutils code has no type annotations so good luck reading it, which you will have to do because... 3. The actual Docutils API is very badly documented. This is easily the biggest flaw. I have implemented a couple of custom directives for my company's docs and it was extremely frustrating to get it working. Pretty much down to using grep.app to search for examples of other random people that have figured it out. So I would strongly recommend not using RST. I've been wondering what would be better for a while - normal Markdown is just not rich enough for good docs. This looks pretty nice though. Latex output is nice, but not really super important in 2022 and definitely not worth the flaws of RestructuredText. Do not use RestructuredText.

euroderf 4y ago
Several previous discussions at HN have suggested that AsciiDoc is better to work with than RST.
__mharrison__ 4y ago
Funny you say that. I spent most of last week porting some of my rst based book authoring tooling to md/pandoc.

__mharrison__ 4y ago

At this point using rst is like advocating for Subversion instead of Git(hub). (Which is actually a good metaphor considering where docutils is hosted...) I say this as a (former) committer to docutils. The LaTeX support is ok in rst if you want to create something similar to a Word document. If you actually wanted to print a book, you need to use something like my tool, rst2nitrile. The Python documentation folks seem to be interested in abstracting Sphinx to markdown as well with MyST... rst is a dead end at this point.