Re:ReStructuredText vs. Markdown for technical documentation
by type0 on Friday February 24, 2017 @03:41PM
(#13727682)
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.
[ Parent
| on HN ]
Re:ReStructuredText vs. Markdown for technical documentation
by david38 on Saturday February 25, 2017 @12:27PM
(#13732599)
I just read some articles on why Linux went from asciidoc to RST. Interesting read.
Re:ReStructuredText vs. Markdown for technical documentation
by type0 on Saturday February 25, 2017 @02:28PM
(#13733303)
I guess you meant this - 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.