4 ms·

> According to John Gruber, the inventor of Markdown: > "Markdown's syntax is intended for one purpose: to be used as a format for writing for the web." > So,

> According to John Gruber, the inventor of Markdown: > "Markdown's syntax is intended for one purpose: to be used as a format for writing for the web." > So, I want to finish this article with the simplest conclusion ever: > "Do not use Markdown for things it was not designed to do. For example, to write documentation." Documentation is a form of writing on the web. Am I missing something?

coldacid 7y ago
"Documentation" and "writing on the web" _do_ intersect, but neither is a subset of the other. A technical manual is documentation but I'd rather die than write one in Markdown, especially when there are much better systems in place for that such as TeX, DocBook, or hell even MS Word.
- Veen 7y ago
  Well, yes. Markdown is the right tool for some documentation. For other documentation, it isn't. Use the right tool for the job. Markdown is a great format for writing basic HTML documents. It sucks for writing books or complex documents, as Matthew Butterick has argued [0]. But that's only a problem if you try to write books or complex documents in Markdown. [0]: https://docs.racket-lang.org/pollen/second-tutorial.html https://docs.racket-lang.org/pollen/second-tutorial.html
  - hak8or 7y ago
    I used markdown for my documentation of a embedded liux system years back (https://brainyv2.hak8or.com/ https://brainyv2.hak8or.com/) and have been very pleased. While it's not a book, it's also not a single page document. The rust official docs are also written in markdown and thrown at mdbook (https://rust-lang.github.io/mdBook/ https://rust-lang.github.io/mdBook/) to generate documentation of a similar style, but it's much more book like. I am pretty much all in for markdown based documentation for almost everything. It does what I need and nothing more. If I need more control over styling, that's a different story, but thankfully almost all my use cases are good enough without such control.
- deleted 7y ago
  [deleted]
- unlinked_dll 7y ago
  I have difficulty putting into words how much I loathe technical writing that is structured anything like a textbook or dissertation. It's a pain in the ass to use, and I wish more people would focus on concise and easily referenced/searched/indexed material in markdown rather than novels written in TeX. For example, Agner Fog's writings are fantastic content, and awful to navigate. The Rust Programming Language does exist in book form, but I find myself referencing it constantly as a technical manual and it would suck to do that if weren't structured the way it is using mdbook. For the love of all that is sacred, please stop writing technical manuals like I'm going to ever going to read the whole thing. Every piece of information should be short, fit entirely in a reasonably sized browser window, be indexed for search, and if it lends itself to cross-referencing it should be filled with links to itself. That's the kind of thing that markdown and site generators using markdown excel at.

coldacid 7y ago

"Documentation" and "writing on the web" _do_ intersect, but neither is a subset of the other. A technical manual is documentation but I'd rather die than write one in Markdown, especially when there are much better systems in place for that such as TeX, DocBook, or hell even MS Word.

Veen 7y ago
Well, yes. Markdown is the right tool for some documentation. For other documentation, it isn't. Use the right tool for the job. Markdown is a great format for writing basic HTML documents. It sucks for writing books or complex documents, as Matthew Butterick has argued [0]. But that's only a problem if you try to write books or complex documents in Markdown. [0]: https://docs.racket-lang.org/pollen/second-tutorial.html https://docs.racket-lang.org/pollen/second-tutorial.html
- hak8or 7y ago
  I used markdown for my documentation of a embedded liux system years back (https://brainyv2.hak8or.com/ https://brainyv2.hak8or.com/) and have been very pleased. While it's not a book, it's also not a single page document. The rust official docs are also written in markdown and thrown at mdbook (https://rust-lang.github.io/mdBook/ https://rust-lang.github.io/mdBook/) to generate documentation of a similar style, but it's much more book like. I am pretty much all in for markdown based documentation for almost everything. It does what I need and nothing more. If I need more control over styling, that's a different story, but thankfully almost all my use cases are good enough without such control.
deleted 7y ago
[deleted]
unlinked_dll 7y ago
I have difficulty putting into words how much I loathe technical writing that is structured anything like a textbook or dissertation. It's a pain in the ass to use, and I wish more people would focus on concise and easily referenced/searched/indexed material in markdown rather than novels written in TeX. For example, Agner Fog's writings are fantastic content, and awful to navigate. The Rust Programming Language does exist in book form, but I find myself referencing it constantly as a technical manual and it would suck to do that if weren't structured the way it is using mdbook. For the love of all that is sacred, please stop writing technical manuals like I'm going to ever going to read the whole thing. Every piece of information should be short, fit entirely in a reasonably sized browser window, be indexed for search, and if it lends itself to cross-referencing it should be filled with links to itself. That's the kind of thing that markdown and site generators using markdown excel at.