Not going to happen. Markdown has been a godsend to me in getting my thoughts in writing in a way others can consume, which is critical in my business. My time is already at a premium, and Markdown is both readable to technical and non-technical users, as well as easily parsable to other formats.
This blog post doesn't get it. It immediately starts touting advanced complex features as a benefit. The benefit of Markdown is the absence of advanced complex features. It's my absolute guarantee that what I write is readable and understandable to all audiences and can easily be converted into rich HTML docs with embedded media.
I am not going to stop using Markdown any time soon, and I hope nobody else does either.
> I am not going to stop using Markdown any time soon, and I hope nobody else does either.
I wish more people would.
I spent a whole 2 minutes fighting with the text styler in a gmail draft today. One of my bullet points ended in styled text, so it really wanted the next bullet point to be that style too. The whole cmd-shift-v for unstyled pasting wasn't the issue. Selecting the text and unstyling it removed the bullet point. The trick was to unstyle all the text except for the first letter, then delete that and type it back in. Would rather just have used MD.
If you're a fan of markdown, take a look at reStructuredText (RST). The syntax is very similar to markdown, e.g. italics, bold, and ``code``, but includes things that are inextricably missing from markdown, like definition lists, tables, footnotes, citations, comments, etc.
I think the best counter argument to your comment is that RST has all of the benefits you've listed (easy to write, readable by technical and non-technical users, and translatable into HTML and other formats) plus more. The syntax of RST is just as lightweight as markdown, making RST appropriate in all of the same places.
In use cases where markdown is under-defined, e.g. technical documentation, there are a variety of competing syntaxes, e.g. the non-standard ``{.foo}`` syntax or the competing flavors of tables. On the other hand, RST has a pair of extensible constructs, called roles and directives, that allows various systems to add features in a portable way. If a particular system doesn't support a particular role/directive, there is a graceful fallback. This is in contrast with markdown where the fallback is to dump your custom syntax into the document as plain text.
"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.
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.
I used markdown for my documentation of a embedded liux system years back (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/) 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.
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.
Sure, Markdown isn't perfect - but it's good enough. It's not so bad that we all should start using asciidoc. For most documentation needs, markdown works great over it's real competitor, plain text.
For me the biggest advantage of markdown is that it works just as well without a parser/formatter. Markdown documents are perfectly readable as-is, in plain source form. All the various alternatives mentioned fail at that.
Oh boy it's been a while since I've read something I disagree with to this extent!
People use Markdown because you can read it both in its formatted version and in its raw unformatted source. Asciidoc is... not that.
Just looking at the examples it looks like a full templating language: conditionals, includes, blocks... I don't want any of this.
> Actually, I was surprised by the fact that so many people think Markdown is a really powerful tool for documentation.
I don't think Markdown is powerful, unless you're counting "power through simplicity". Markdown's lack of power is a positive: there is a very limited set of things I need to learn in order to use it effectively and someone who knows literally nothing about Markdown can read its source immediately.
I don't see how AsciiDoc source is any more or less readable than Markdown. AsciiDoc does everything Markdown does, but since there's a specification there are no inconsistencies.
It also has features beyond that. You don't need to use them.
The argument that certain features are optional overlooks the fact that other people can and will use them, especially in collaborative projects.
That's not a death knell. You can gate the features behind style guides, linters, or social conventions. However, those are costs in and of themselves. Additional features of a language always have a carrying cost, even behind optional flags.
But people will, though. If you're lucky enough to be there at the start of project you could establish a list of allowed functionality but at that point you're documenting your documentation, which feels, uh, sub optimal.
Weak semantics are a feature not a bug. Flavour standardisation is happening (see https://commonmark.org/). The ability to abuse notation a little to provide extensions is actually rather practical. Things like templating, inline code, slides.
The point of Markdown is to be legible as plain text, without being run through a rendering engine. Rendering engines are a bonus, but not required. Based on the samples shared, ASCII Doc is hard to read without a renderer (just like HTML). I appreciate being able to use a simple, well thought out set of conventions to facilitate writing in plain text files. Markdown isn’t perfect, but it helps make plain text documents a little more readable, especially when dealing with hyperlinks.
What is wrong with you... Markdown is structured enough to be ingested by a parser. You can input or output Markdown from and into any other structure you prefer... :D
Who’s the idiot who made google docs and didn’t focus-test it for software docs? You need a third party add on just for code blocks ffs. I really wanted to use Google Docs for this but it just didn’t work. Confluence makes you switch between edit mode and view mode just like Markdown, and Notion is cool but has limited features for this application (no api)
Sadly there’s no really mind blowing solution for documentation in 2020. Crazy. Markdown for me for now
Can't we just use JSX or XML? Those both beat this house of cards formed out of one-off and nonstandard extensions, parsers, and pipelines built around Markdown, which in itself is deficient and prompts the creation of these fragmented ecosystems.
Asciidoc and RST fall down because they act like Excel: a UI which expects its user to work through a tutorial on pivot tables. The success of Markdown comes from knowing that its users don't want to spend any more time learning it than they spend learning how their bank website works.
So you want to preserve that navigability.
A source-reader isn't going to have the time to learn "conventions" like rails asks them to do. So for any deviations from markdown, you would want the reader of the source to be able to see how those are defined.
I think the sweet spot would be markdown-biased JSX.
The directory structure would be:
- `/components` with two file to start: index.jsx, which would import the `Markdown` element from the library and re-export it. There would also be custom-component-example.jsx to demonstrate and document the interface expected by the renderer. Any custom components go in this directory.
- `/theme` which has theme information across the whole site. If you want a different theme for a different part of the page, that is a different site
- `/source` with a tree of mostly .md files, but occasionally .jsxmd files which tell the source-reader where the component was defined, but otherwise get out of the way. A .jsxmd file might look like this:
```
from '../../components' import Markdown, Aside;
export default () => (<Markdown>
## JavaScript Resources
The React documentation assumes some familiarity with programming in the JavaScript language.
You don’t have to be an expert, but it’s harder to learn both React and JavaScript at the same time.
We recommend going through this JavaScript overview to check your knowledge level.
It will take you between 30 minutes and an hour but you will feel more confident learning React.
<Aside>
#### Tip
Whenever you get confused by something in JavaScript,
MDN and javascript.info are great websites to check.
There are also community support forums where you can ask for help.
</Aside>
## Practical Tutorial
If you prefer to learn by doing, check out our practical tutorial.
In this tutorial, we build a tic-tac-toe game in React.
You might be tempted to skip it because you’re not into building games — but give it a chance.
The techniques you’ll learn in the tutorial are fundamental to building any React apps,
and mastering it will give you a much deeper understanding.
</Markdown>)
This seems worse for the markdown use case. The tags are distracting, and arbitrary use cases (like github readmes, or in browser previews) need to run JS code to render it, which probably spits out HTML specific output and requires all renderers to pull in the web stack.
Compare that to markdown, where in the worst case, the .md file is readable as a doc in isolation.
> Can't we just use JSX or XML? Those both beat this house of cards formed out of one-off and nonstandard extensions, parsers, and pipelines built around Markdown
Not really, JSX is very standardized and consistent to parse because it's a superset of JavaScript which is also standardized. The only bit that isn't consistent across toolchains is imports, which still need work but generally function with a small amount of massaging the configs.
Whether or not Markdown works for documenting your project depends on your definition of "documentation" and "works." Blog posts telling you to stop or start doing something are myopic and rarely helpful.
> most people are talking a different kind of "documentation". Most people are thinking of "basic instructions + API", I'm thinking "multithousand-word manuals and reference materials". The latter needs a lot of stuff the former doesn't
With this context, I think it absolutely makes sense that if you're writing something structured (like a book), Markdown may not be the best choice to capture that structure. Of course, if you aren't already sure you're going to have enough documentation "content", then the best choice is whatever gets you writing at all in the first place, whether it's Markdown or Google Docs or emails to colleagues or whatever.
That's pretty illustrative, in that it demonstrates how actually thinking about what you are trying to communicate is going to be much more important than what format you've used to write it. That article would be equally poor in html, latex, markdown or reStructuredText.
Hah! It's almost as if the developer "tool wars" are stupid because everything has its place. Every tool is useful to someone; someone wrote it for a purpose.
I think an article like this should be called, "markdown is good, but fur large documentation requirements try ASCIIdoc" and approach it from that angle, and then people would have a chance to compare the two, and maybe use a new technology, without the clickbait title.
I've used rst. It was an unmitigated disaster for anyone except the rst-fan who initiated the project. We eventually hauled the contents over to Confluence, because it was less painful that way. If you can imagine. Later on, we started using markdown.
All the fancy features and attempts to smooth over complexity are a hindrance to having text that is easily writable. The complexity is there for a real text processing engine, you can't avoid it.
I either write LaTeX or org/Markdown, if given the choice. Note that org and markdown are trivially usable if the renderer explodes under you.
Pass. Markdown is pragmatic, works well and is most importantly, easy to learn and maintain.
Asciidoc is well-intentioned but is way too complex. Variables, extensible formatting language, and conditionals really don't fit for 99% plus use cases where you'd use Markdown... and if they do, they are as a part of a web templating engine that is being fed markdown.
Markdown is far from perfect, yet it remains my format of choice for most writing that requires some formatting. I even write my longer emails in Markdown and then paste them into an email app (would be great if gmail accepted markdown).
If you require as much power for your documentation as demonstrated and don't mind the relative obscurity in the source, why not just write it in your favorite language and have it output to whatever format you want? Most languages have a means of entering muti-line strings. And then you can include all the bells and whistles your language and its ecosystem provides.
78 comments
[ 4.5 ms ] story [ 139 ms ] threadThis blog post doesn't get it. It immediately starts touting advanced complex features as a benefit. The benefit of Markdown is the absence of advanced complex features. It's my absolute guarantee that what I write is readable and understandable to all audiences and can easily be converted into rich HTML docs with embedded media.
I am not going to stop using Markdown any time soon, and I hope nobody else does either.
I wish more people would.
I spent a whole 2 minutes fighting with the text styler in a gmail draft today. One of my bullet points ended in styled text, so it really wanted the next bullet point to be that style too. The whole cmd-shift-v for unstyled pasting wasn't the issue. Selecting the text and unstyling it removed the bullet point. The trick was to unstyle all the text except for the first letter, then delete that and type it back in. Would rather just have used MD.
(ia writer - I don't work for them I just like their product)
I think the best counter argument to your comment is that RST has all of the benefits you've listed (easy to write, readable by technical and non-technical users, and translatable into HTML and other formats) plus more. The syntax of RST is just as lightweight as markdown, making RST appropriate in all of the same places.
In use cases where markdown is under-defined, e.g. technical documentation, there are a variety of competing syntaxes, e.g. the non-standard ``{.foo}`` syntax or the competing flavors of tables. On the other hand, RST has a pair of extensible constructs, called roles and directives, that allows various systems to add features in a portable way. If a particular system doesn't support a particular role/directive, there is a graceful fallback. This is in contrast with markdown where the fallback is to dump your custom syntax into the document as plain text.
FWIW, this comment is valid RST.
https://docutils.sourceforge.io/docs/ref/rst/restructuredtex...
P.S. The HN web UI swallows my examples of bold and italics in the first paragraph.
Markdown is text, so very portable. The flavors of markdown can be ignored.
> "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?
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
The rust official docs are also written in markdown and thrown at 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.
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.
People use Markdown because you can read it both in its formatted version and in its raw unformatted source. Asciidoc is... not that.
Just looking at the examples it looks like a full templating language: conditionals, includes, blocks... I don't want any of this.
> Actually, I was surprised by the fact that so many people think Markdown is a really powerful tool for documentation.
I don't think Markdown is powerful, unless you're counting "power through simplicity". Markdown's lack of power is a positive: there is a very limited set of things I need to learn in order to use it effectively and someone who knows literally nothing about Markdown can read its source immediately.
It also has features beyond that. You don't need to use them.
Edit: here's an example from KiCAD's documentation ("Raw" to view the source, as GitHub supports AsciiDoc as well as Markdown) https://github.com/KiCad/kicad-doc/blob/master/src/getting_s...
You do if you are reading a source that uses them.
That's not a death knell. You can gate the features behind style guides, linters, or social conventions. However, those are costs in and of themselves. Additional features of a language always have a carrying cost, even behind optional flags.
But people will, though. If you're lucky enough to be there at the start of project you could establish a list of allowed functionality but at that point you're documenting your documentation, which feels, uh, sub optimal.
A recent discussion thread on exactly the same topic: https://news.ycombinator.com/item?id=22675165
Sadly there’s no really mind blowing solution for documentation in 2020. Crazy. Markdown for me for now
So you want to preserve that navigability.
A source-reader isn't going to have the time to learn "conventions" like rails asks them to do. So for any deviations from markdown, you would want the reader of the source to be able to see how those are defined.
I think the sweet spot would be markdown-biased JSX.
The directory structure would be:
- `/components` with two file to start: index.jsx, which would import the `Markdown` element from the library and re-export it. There would also be custom-component-example.jsx to demonstrate and document the interface expected by the renderer. Any custom components go in this directory.
- `/theme` which has theme information across the whole site. If you want a different theme for a different part of the page, that is a different site
- `/source` with a tree of mostly .md files, but occasionally .jsxmd files which tell the source-reader where the component was defined, but otherwise get out of the way. A .jsxmd file might look like this:
```
```Compare that to markdown, where in the worst case, the .md file is readable as a doc in isolation.
Why wouldn't this be true for JSX?
> most people are talking a different kind of "documentation". Most people are thinking of "basic instructions + API", I'm thinking "multithousand-word manuals and reference materials". The latter needs a lot of stuff the former doesn't
With this context, I think it absolutely makes sense that if you're writing something structured (like a book), Markdown may not be the best choice to capture that structure. Of course, if you aren't already sure you're going to have enough documentation "content", then the best choice is whatever gets you writing at all in the first place, whether it's Markdown or Google Docs or emails to colleagues or whatever.
I think an article like this should be called, "markdown is good, but fur large documentation requirements try ASCIIdoc" and approach it from that angle, and then people would have a chance to compare the two, and maybe use a new technology, without the clickbait title.
I agree with everyone here, though, that markdown is great for it's simplicity.
All the fancy features and attempts to smooth over complexity are a hindrance to having text that is easily writable. The complexity is there for a real text processing engine, you can't avoid it.
I either write LaTeX or org/Markdown, if given the choice. Note that org and markdown are trivially usable if the renderer explodes under you.
Asciidoc is well-intentioned but is way too complex. Variables, extensible formatting language, and conditionals really don't fit for 99% plus use cases where you'd use Markdown... and if they do, they are as a part of a web templating engine that is being fed markdown.
If you require as much power for your documentation as demonstrated and don't mind the relative obscurity in the source, why not just write it in your favorite language and have it output to whatever format you want? Most languages have a means of entering muti-line strings. And then you can include all the bells and whistles your language and its ecosystem provides.