3 ms·

Don’t Use Markdown for Documentation (2016)

55 points by yinso 9y ago

gcb0 9y ago
only if github offered sphinx support.
- yorwba 9y ago
  They do, unless there's more to Sphinx than just reStructuredText? See the list of supported markups here: https://github.com/github/markup/blob/master/README.md#markups https://github.com/github/markup/blob/master/README.md#marku...
  - dozzie 9y ago
    Plugins, like autodoc.
rlabrecque 9y ago
What we ended up doing was just reusing our existing bbcode support. Markdown wasn't giving us anything over it really and it was easier to reason with, especially for non-technical folks and translators. We were able to extend it for our use cases much easier. All of this after the initial plan was to use Markdown.
paulcole 9y ago
Since most people commenting will do so without even opening, let alone reading, the linked article, let me draw your attention to the last line: >Full Disclosure: I work on a product, Read the Docs, which is based on Sphinx, so my views are likely biased.
deleted 9y ago
[deleted]
fnayr 9y ago
Thanks for the alternate suggestions (biased as they may be). My biggest pain point when writing doc in md is tables. They are so hard to parse in the raw text, and I constantly have to be checking the rendered output to make any edits/find my place. Does anyone know of a good alternative to md (including Sphinx and Asciidoctor) that deals with tables better?
- jitl 9y ago
  I use HTML <table> in my markdown. Works great. Many already know the syntax. Supports large table cell bodies in a readable manner. The downside is the syntax is noisy compared to your average markdown, and the tables don’t make much sense in text view.
  - fnayr 9y ago
    Ah yes I hadn't really thought about that for some reason. Do you view HTML as something that should only be used where necessary in MD or just go crazy with it?
    - jitl 9y ago
      I use it when it’s needed: 1. Tables 2. Collapsable sections with <detail> 3. Color-coding with <span style=“...”> or <span class=“...”>
ChicagoDave 9y ago
If I can anyone to actually write documentation, I don’t care what tool they use as long as it’s a reasonably accepted tool. Any flavor of markdown qualifies.
jitl 9y ago
The litany of issues about Markdown flavors and interop issues there doesn’t ring true to me: most tools these days use Github-flavored Markdown. Never had a parsing problem between the various Ruby, Python, and C markdown libs I’ve used over the years. Getting engineers to contribute to docs is hard enough; it’d be quite a barrier in my org to also teach them a new markup language. Everyone already knows Markdown or some subset of HTML.
nixpulvis 9y ago
Rust seems to disagree, and I'm glad of it. Documentation is easy to write, and reasonably extensible. Sure there are things I wish to see added (LaTeX math mode would be awesome) but there's nothing really stopping this from happening, even if it's not part of a universal standard.
- Azareus 9y ago
  That reminds me, pandoc offers compilation of latex fragments inside markdown source when exporting to pdf, which is how I typeset almost all of my math. This is of course not even close to the same thing as official support would be, but it's good to have in a pinch, so you can typeset some math without having to bust out a latex toolchain you might not have used for a long time. PS: pandoc offers a command-line flag to set the latex engine, which means you can use XeTeX or LuaTeX for better unicode support.
dang 9y ago
Discussed at the time: https://news.ycombinator.com/item?id=11292280 https://news.ycombinator.com/item?id=11292280.
firegrind 9y ago
The alternatives mention python and ruby. What drew me to markdown in the first place was the absence of dependencies.
chipotle_coyote 9y ago
Articles like this come up every so often, and they usually point to all the problems with Markdown -- slightly incompatible implementations, nonstandard extensions, how difficult it is to correctly parse in all cases, how mixing non-tag markup and HTML offends proper sensibilities, etc. And I can't say that they're wrong, per se. Markdown is a terrific example of "worse is better." That's the thing, though -- the whole argument for "worse is better" is that it produces more successful software. In practice, it turns out that it's pretty easy for most people to write most things in Markdown, no matter which processor they're using, just merrily mixing in HTML (or template tags) when they need to. The arguments for AsciiDoc and ReStructuredText usually boil down to "they make difficult things easier," which they do -- but they tend to make more common things (links, images, blockquotes, footnotes [not technically "standard" Markdown but the [^fn] notation is nearly universal]) a little more difficult. Markdown, by contrast, makes the things you're typing all the time trivial, while still letting you do anything that you can do in HTML by, well, letting you do it in HTML.
h3rald 9y ago
While I understand the point that the article is trying to make, i.e. that no "standard" markdown offers sufficient features to write documentation, I don't think that it matters too much as long as the final result is good. I always wanted to write manuals and documentation in markdown (or any other lightweight markup language for the matter) but not even a specialized flavor of markdown was able to provide all the features that a technical writer expects from a documentation tools (I am talking especially about block-level formatting and content reuse). So I came up with HastyScribe (https://h3rald.com/hastyscribe/ https://h3rald.com/hastyscribe/) and then HastySite (https://h3rald.com/hastysite/ https://h3rald.com/hastysite/). Basically, I used Discount as a base and added features on top of it. I am now using it for all my sites and all the documentation of my open source projects. And I know of at least one company that is using HastyScribe for their own user documentation. OK, there's some degree of vendor lock-in, but at least the final result is OK and both tools are open source. For more info and a preview of what an HastyScribe document looks like, here's the user guide: https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm
tgp 9y ago
Markdown is fine for small snippets, READMEs, Github comments etc., but I don't think it's suitable for a longer document such as software documentation. After thinking about that problem and exploring options for a while I have come to believe that some lightweight markup that can be converted to DocBook may be the way to go. I have blogged about such a pipeline here: https://nablux.net/tgp/weblog/2017/04/02/lightweight-semantic-markup/ https://nablux.net/tgp/weblog/2017/04/02/lightweight-semanti...

55 points by yinso 9y ago

gcb0 9y ago

only if github offered sphinx support.

yorwba 9y ago
They do, unless there's more to Sphinx than just reStructuredText? See the list of supported markups here: https://github.com/github/markup/blob/master/README.md#markups https://github.com/github/markup/blob/master/README.md#marku...
- dozzie 9y ago
  Plugins, like autodoc.

rlabrecque 9y ago

What we ended up doing was just reusing our existing bbcode support. Markdown wasn't giving us anything over it really and it was easier to reason with, especially for non-technical folks and translators. We were able to extend it for our use cases much easier. All of this after the initial plan was to use Markdown.

paulcole 9y ago

Since most people commenting will do so without even opening, let alone reading, the linked article, let me draw your attention to the last line: >Full Disclosure: I work on a product, Read the Docs, which is based on Sphinx, so my views are likely biased.

deleted 9y ago

[deleted]

fnayr 9y ago

Thanks for the alternate suggestions (biased as they may be). My biggest pain point when writing doc in md is tables. They are so hard to parse in the raw text, and I constantly have to be checking the rendered output to make any edits/find my place. Does anyone know of a good alternative to md (including Sphinx and Asciidoctor) that deals with tables better?

jitl 9y ago
I use HTML <table> in my markdown. Works great. Many already know the syntax. Supports large table cell bodies in a readable manner. The downside is the syntax is noisy compared to your average markdown, and the tables don’t make much sense in text view.
- fnayr 9y ago
  Ah yes I hadn't really thought about that for some reason. Do you view HTML as something that should only be used where necessary in MD or just go crazy with it?
  - jitl 9y ago
    I use it when it’s needed: 1. Tables 2. Collapsable sections with <detail> 3. Color-coding with <span style=“...”> or <span class=“...”>

ChicagoDave 9y ago

If I can anyone to actually write documentation, I don’t care what tool they use as long as it’s a reasonably accepted tool. Any flavor of markdown qualifies.

jitl 9y ago

The litany of issues about Markdown flavors and interop issues there doesn’t ring true to me: most tools these days use Github-flavored Markdown. Never had a parsing problem between the various Ruby, Python, and C markdown libs I’ve used over the years. Getting engineers to contribute to docs is hard enough; it’d be quite a barrier in my org to also teach them a new markup language. Everyone already knows Markdown or some subset of HTML.

nixpulvis 9y ago

Rust seems to disagree, and I'm glad of it. Documentation is easy to write, and reasonably extensible. Sure there are things I wish to see added (LaTeX math mode would be awesome) but there's nothing really stopping this from happening, even if it's not part of a universal standard.

Azareus 9y ago
That reminds me, pandoc offers compilation of latex fragments inside markdown source when exporting to pdf, which is how I typeset almost all of my math. This is of course not even close to the same thing as official support would be, but it's good to have in a pinch, so you can typeset some math without having to bust out a latex toolchain you might not have used for a long time. PS: pandoc offers a command-line flag to set the latex engine, which means you can use XeTeX or LuaTeX for better unicode support.

dang 9y ago

Discussed at the time: https://news.ycombinator.com/item?id=11292280 https://news.ycombinator.com/item?id=11292280.

firegrind 9y ago

The alternatives mention python and ruby. What drew me to markdown in the first place was the absence of dependencies.

chipotle_coyote 9y ago

Articles like this come up every so often, and they usually point to all the problems with Markdown -- slightly incompatible implementations, nonstandard extensions, how difficult it is to correctly parse in all cases, how mixing non-tag markup and HTML offends proper sensibilities, etc. And I can't say that they're wrong, per se. Markdown is a terrific example of "worse is better." That's the thing, though -- the whole argument for "worse is better" is that it produces more successful software. In practice, it turns out that it's pretty easy for most people to write most things in Markdown, no matter which processor they're using, just merrily mixing in HTML (or template tags) when they need to. The arguments for AsciiDoc and ReStructuredText usually boil down to "they make difficult things easier," which they do -- but they tend to make more common things (links, images, blockquotes, footnotes [not technically "standard" Markdown but the [^fn] notation is nearly universal]) a little more difficult. Markdown, by contrast, makes the things you're typing all the time trivial, while still letting you do anything that you can do in HTML by, well, letting you do it in HTML.

h3rald 9y ago

While I understand the point that the article is trying to make, i.e. that no "standard" markdown offers sufficient features to write documentation, I don't think that it matters too much as long as the final result is good. I always wanted to write manuals and documentation in markdown (or any other lightweight markup language for the matter) but not even a specialized flavor of markdown was able to provide all the features that a technical writer expects from a documentation tools (I am talking especially about block-level formatting and content reuse). So I came up with HastyScribe (https://h3rald.com/hastyscribe/ https://h3rald.com/hastyscribe/) and then HastySite (https://h3rald.com/hastysite/ https://h3rald.com/hastysite/). Basically, I used Discount as a base and added features on top of it. I am now using it for all my sites and all the documentation of my open source projects. And I know of at least one company that is using HastyScribe for their own user documentation. OK, there's some degree of vendor lock-in, but at least the final result is OK and both tools are open source. For more info and a preview of what an HastyScribe document looks like, here's the user guide: https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm

tgp 9y ago

Markdown is fine for small snippets, READMEs, Github comments etc., but I don't think it's suitable for a longer document such as software documentation. After thinking about that problem and exploring options for a while I have come to believe that some lightweight markup that can be converted to DocBook may be the way to go. I have blogged about such a pipeline here: https://nablux.net/tgp/weblog/2017/04/02/lightweight-semantic-markup/ https://nablux.net/tgp/weblog/2017/04/02/lightweight-semanti...