Don't use markdown for documentation (2018)(mister-gold.pro)
mister-gold.pro
Don't use markdown for documentation (2018)
https://mister-gold.pro/posts/en/asciidoc-vs-markdown/
78 comments
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.
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.
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.
You may be interested: https://markdown-here.com/features.html
Same! I even paid for an app (something I never do) just because it supports creating markdown files on your iphone
(ia writer - I don't work for them I just like their product)
(ia writer - I don't work for them I just like their product)
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.
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.
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.
I don't mind giving up Markdown for writing docs, but only if we all agree to use Org-mode text instead.
Org-mode is another powerful alternative to markdown. Github can render org-mode documentation.
>Lock-In and Lack of Portability. The tons of flavors and the lack of semantic support results in a lock-in.
Markdown is text, so very portable. The flavors of markdown can be ignored.
Markdown is text, so very portable. The flavors of markdown can be ignored.
> 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?
> "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?
"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.
[0]: https://docs.racket-lang.org/pollen/second-tutorial.html
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
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.
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.
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.
[deleted]
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.
No. Markdown is the sweet spot between plain-text and HTML, and that makes it perfect for the task.
No way!
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.
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.
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...
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...
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.
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.
> You don't need to use them.
You do if you are reading a source that uses them.
You do if you are reading a source that uses them.
> You don't need to use them.
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.
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.
Here's a full AsciiDoc example: http://asciidoc.org/asciidoc.txt I get that you prefer Markdown but AsciiDoc isn't a very complicated format.
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.
As long as the converted html is provided for the reader, markdown is perfect
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
(Discussion-wise, the link is a dupe.)
A recent discussion thread on exactly the same topic: https://news.ycombinator.com/item?id=22675165
A recent discussion thread on exactly the same topic: https://news.ycombinator.com/item?id=22675165
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
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:
```
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.
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
Why wouldn't this be true for JSX?
Why wouldn't this be true for JSX?
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.
Consider reflecting on what you or someone else might mean by "documentation". A submission from 3 hours ago titled "Please don't write your documentation in Markdown" was on the front page earlier: https://news.ycombinator.com/item?id=22675165 — but according to its author (https://twitter.com/hillelogram/status/1242502542212333576),
> 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.
> 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 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.
If the author wants to write a book, then they're still using the wrong tool, they should be using LaTeX.
I agree with everyone here, though, that markdown is great for it's simplicity.
I agree with everyone here, though, that markdown is great for it's simplicity.
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.
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.
At least he's not vehemently advocating Word.
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.
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.
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.
> Note: I Love Markdown
Disagree. Actually I've written my whole thesis in Markdown and it was distraction free, practical and very easy to work this way.
If somebody needs the link to a good Markdown thesis template: https://github.com/tompollard/phd_thesis_markdown
If somebody needs the link to a good Markdown thesis template: https://github.com/tompollard/phd_thesis_markdown
I think the problem here comes in disagreement over the meaning of "documentation". When we talk about documentation for a program, do we mean the man pages? The README? The help docs? The API specifications? Or a long-form document or manual describing the use of the program, such as 'The C Programming Language' or the Camel books?
For all of the preceding except the long-form document at the end, I'd say Markdown is a perfect tool. It's portable, it's readable as-is, and it's supported on a variety of platforms including all the various git hosting platforms with native parse-and-render. That makes it the perfect tool for straightforward, uncomplicated documents.
For more complicated, formally structured documents, however, Markdown is awful. I've worked on a number of structured documents like public standards docs, procedures docs, and formal specs in Markdown, and they're a pain in the neck. Without using one of the less portable variants like Kramdown, you quickly find yourself having to work your way around the lack of formatting in table cells or specific list-numbering (or lettered lists at all), and so forth, and the less-portable variants mean you suddenly have to worry about your publishing/rendering chain to make sure everything supports what you're using in the form you're using it.
The rubric for me has been this: if the way the content looks/is structured on rendering matters, use one of the more structured tools like AsciiDoc or even Word. If the presentation of the content isn't as crucial, Markdown is a perfect tool (and makes a good default!).
For all of the preceding except the long-form document at the end, I'd say Markdown is a perfect tool. It's portable, it's readable as-is, and it's supported on a variety of platforms including all the various git hosting platforms with native parse-and-render. That makes it the perfect tool for straightforward, uncomplicated documents.
For more complicated, formally structured documents, however, Markdown is awful. I've worked on a number of structured documents like public standards docs, procedures docs, and formal specs in Markdown, and they're a pain in the neck. Without using one of the less portable variants like Kramdown, you quickly find yourself having to work your way around the lack of formatting in table cells or specific list-numbering (or lettered lists at all), and so forth, and the less-portable variants mean you suddenly have to worry about your publishing/rendering chain to make sure everything supports what you're using in the form you're using it.
The rubric for me has been this: if the way the content looks/is structured on rendering matters, use one of the more structured tools like AsciiDoc or even Word. If the presentation of the content isn't as crucial, Markdown is a perfect tool (and makes a good default!).
The ifdef and ifeval features are nice, but I would not take advice about document formatting from anyone who uses full justification layout.
Most of these reasons why Markdown Fails are weak at best.
The 5th reason especially You can convert markdown into other formats such as PDF, Word, Media WIKI etc using pandoc (I am sure there are other programs). It is trivial to write a shell script or similar to convert markdown files into another format.
> After that, it is hard to migrate to another tool, as custom-defined HTML classes and flavor's features won't work outside the current set of tools and page designs.
That contradicts his Lack of Extensibility. Typically anything custom you do outside what is supported officially by the tools maintainer is your own lookout.
Markdown is a like a lot of things that succeed. It is good enough to produce well formatted documentation to be read by a client and simple enough for people to learn it relatively quickly without headaches.
The 5th reason especially You can convert markdown into other formats such as PDF, Word, Media WIKI etc using pandoc (I am sure there are other programs). It is trivial to write a shell script or similar to convert markdown files into another format.
> After that, it is hard to migrate to another tool, as custom-defined HTML classes and flavor's features won't work outside the current set of tools and page designs.
That contradicts his Lack of Extensibility. Typically anything custom you do outside what is supported officially by the tools maintainer is your own lookout.
Markdown is a like a lot of things that succeed. It is good enough to produce well formatted documentation to be read by a client and simple enough for people to learn it relatively quickly without headaches.
Don't tell me what to do.
Also, I like markdown.
Also, I like markdown.
This is just too much. Nobody wants to have a linter for their code “documentation”! Oh we’re gonna have the linter in our CI pipeline too probably.
The author is missing the difference with markdown, which seems to be the main blocker here. But Asciidoc is more like markdown + extras. It's (optionally) backward compatible with markdown, so unless you use those extra features, it's unlikely that an average person will distinguish the difference. So you can continue to write markdown as usual, only add extra stuff when you learn it.
The minor difference is things like how you embed images, and so on. _For me_, the main feature of the Asciidoc is the syntax for tables. Tables are important for good documentation, but with markdown it's really hard to write with tables, it makes a document a total mess and ruins the whole idea.
The minor difference is things like how you embed images, and so on. _For me_, the main feature of the Asciidoc is the syntax for tables. Tables are important for good documentation, but with markdown it's really hard to write with tables, it makes a document a total mess and ruins the whole idea.
Both alternatives look like garbage as plain text.
YAMTF: Yet Another Mouth To Feed. Noun:
"Tool that purports to simplify, yet which exacerbates complexity."
If one is adept at the HTML, it is not infrequently faster to just use that instead of figuring out how we do X in Y new tool.
"Tool that purports to simplify, yet which exacerbates complexity."
If one is adept at the HTML, it is not infrequently faster to just use that instead of figuring out how we do X in Y new tool.
Whenever I need anything more capable than markdown I go straight to HTML/CSS. I understand this often isn't an option for technical writers who aren't developers but I'd rather not take the time to learn any niche tools in between. I guess you could say "when you can't markdown, markup!"
I prefer plain text.
Plain text is best viewed in a program that turns URLs into follow-able links. I use vim. Press 'gx' in vim to open the URL under the cursor in your browser.
Plain text is far more ubiquitous than Markdown, although Markdown is slowly gaining ground.
Like Markdown, plain text also has different flavours. UTF-8 is my personal favourite.
Like Markdown, plain text is easy to read in its source form.
Unlike Markdown, there are clear standards for the rendering of plain text.
In plain text, non-savvy people are not confused by ~this sort of thing and~ [this sort of thing](http://example.com).
In plain text, a line break is a line break.
Swap out your README.md for a README today!
Plain text is best viewed in a program that turns URLs into follow-able links. I use vim. Press 'gx' in vim to open the URL under the cursor in your browser.
Plain text is far more ubiquitous than Markdown, although Markdown is slowly gaining ground.
Like Markdown, plain text also has different flavours. UTF-8 is my personal favourite.
Like Markdown, plain text is easy to read in its source form.
Unlike Markdown, there are clear standards for the rendering of plain text.
In plain text, non-savvy people are not confused by ~this sort of thing and~ [this sort of thing](http://example.com).
In plain text, a line break is a line break.
Swap out your README.md for a README today!
rST fits all the goals of both sides of this argument. Reads well in original format, supports more features than Markdown.
I’m in utter disagreement. As others have noted, the brilliance of Markdown is its simplicity — both in use and in readability. Since 2008, I've successfully taught so many people — technical and non-technical — how to use Markdown.
The complexities of the various flavors is true — and the author has resisted supporting any of those flavors for that reason — but the way around that, in my opinion, is to treat each flavor as its own language. If I get to the point where my needs require I use another flavor of Markdown (I personally use Fletcher Penny's MultiMarkdown superset and have for ~12 years or so), it is with the understanding that those features are for that project. That’s the same approach I use for any collaborative effort.
And frankly, if I have to look at pandoc or as Asciidoc or something else, I’m already complicating my life and the life of the people I work with. Which is fine if that’s the premise and if that is the tool we need for our job.
I can and do use Markdown for documentation of almost anything I do, persona, side-hustle, or for work. The Microsoft Docs team (I’m not on that team but I work with them from time to time), even has a VS Code extension pack with a collection of plugins specifically geared to how we do docs. Markdown is a massive part of the workflow, in large part because it is so readable. I honestly wish Microsoft Word and OneNote had native Markdown support (OneNote especially. Yes, there are some kludgy plugins but I mean native).
I have never been a technical writer as a profession (I’ve written my share of documentation, however), but I was a journalist for a decade and wrote millions of words in Markdown in my text editor. Markdown might not be perfect for all documentation types, but to pretend or even encourage people to NOT use it is a really, really bad take.
The complexities of the various flavors is true — and the author has resisted supporting any of those flavors for that reason — but the way around that, in my opinion, is to treat each flavor as its own language. If I get to the point where my needs require I use another flavor of Markdown (I personally use Fletcher Penny's MultiMarkdown superset and have for ~12 years or so), it is with the understanding that those features are for that project. That’s the same approach I use for any collaborative effort.
And frankly, if I have to look at pandoc or as Asciidoc or something else, I’m already complicating my life and the life of the people I work with. Which is fine if that’s the premise and if that is the tool we need for our job.
I can and do use Markdown for documentation of almost anything I do, persona, side-hustle, or for work. The Microsoft Docs team (I’m not on that team but I work with them from time to time), even has a VS Code extension pack with a collection of plugins specifically geared to how we do docs. Markdown is a massive part of the workflow, in large part because it is so readable. I honestly wish Microsoft Word and OneNote had native Markdown support (OneNote especially. Yes, there are some kludgy plugins but I mean native).
I have never been a technical writer as a profession (I’ve written my share of documentation, however), but I was a journalist for a decade and wrote millions of words in Markdown in my text editor. Markdown might not be perfect for all documentation types, but to pretend or even encourage people to NOT use it is a really, really bad take.
I've done my time with LaTeX for years, arguing for its virtues, and once I discovered that I could write Markdown and convert it to LaTeX with Pandoc, I haven't looked back. I feel like a lot (though admittedly not all) of the Markdown rough-edges go away after that. Granted, I don't use Pandoc for "documentation", just technical writing, so maybe that's irrelevant.
Most of the criticisms listed here aren't wrong exactly, but I feel are a bit short-sighted. If you tell people to stop using a language that's well-supported as a rendering tarket in their favorite code-sharing repo, they're not just going to switch to AsciiDoc or TeX and host a PDF on Dropbox...they're going to stop writing documentation entirely, or just do some crappy attempt of doing "documentation in the comments".
As it stands, I think slightly-NSFW quote says it well: "Documentation is like sex...when it's good it's great, when it's bad it's still better than nothing.".
Most of the criticisms listed here aren't wrong exactly, but I feel are a bit short-sighted. If you tell people to stop using a language that's well-supported as a rendering tarket in their favorite code-sharing repo, they're not just going to switch to AsciiDoc or TeX and host a PDF on Dropbox...they're going to stop writing documentation entirely, or just do some crappy attempt of doing "documentation in the comments".
As it stands, I think slightly-NSFW quote says it well: "Documentation is like sex...when it's good it's great, when it's bad it's still better than nothing.".
I think the last sentence hurts your point. There is definitely painful sex which is worse than nothing and there is definitely misleading documentation which is worse than nothing.
Markdown is good because it is much easier for someone to notice it needs to be updated and to fix it without yak-shaving.
Markdown is good because it is much easier for someone to notice it needs to be updated and to fix it without yak-shaving.
Fair enough, I just thought it was a humorous aphorism more than anything.
Yes, documentation can be out of date but even then it's often still more useful than not having any. I agree with markdown being a lower barrier of entry than most other stuff, increasing its appeal.
Yes, documentation can be out of date but even then it's often still more useful than not having any. I agree with markdown being a lower barrier of entry than most other stuff, increasing its appeal.
I feel for the author. However, I strongly disagree with the conclusions here in practice. A lot of this boils down to "other tools are better," and that's true, but the issue is that it's really, really hard to get people to write documentation, and handing them a perfect but complex tool means they're less likely to actually go through with it.
I've written every kind of documentation in Markdown, and it's not a panacea, but it does work. I'll talk about the article's points first, though:
> Lack of specification
https://commonmark.org/. It's not perfect, but GFM and it are (slowly) unifying. Pick one, document that that's the one you support, and you're done.
> Flavors
See answer 1.
> Lack of Extensibility
While it does not have an extension system, that doesn't mean that you can't do it. As long as you only add things, you should be good to go. Most things you'd want that aren't in the spec proper have some sort of existing extension that will solve your problems.
This is not ideal, but it's also not insurmountable. This is the only true negative I agree with on this list, I just don't think it's the end of the world.
> Lack of Semantic Meaning.
While this is true in a sense, at the same time, CommonMark lets you put any string on a code fence, which means that you can add whatever sematnic you'd like.
> Markdown is now dependent on specific HTML classes, and page design
No more dependent on those classes than on whatever other semantic marker you were trying to do, and if you want to change them, do what you'd have to do with the semantic: configure your tooling to put out something else.
> Document content is no longer portable to other output formats
This problem would still exist if semantics were there; someone has to write the mapping.
> Conversion to other markup tools and page designs becomes much harder
I disagree, but there's also no justification, so it's hard to respond.
> Lock-In and Lack of Portability.
This is a non-issue in practice. It's just like any other format.
-------------------------------------
All of Rust's documentation is in Markdown. We've overcome these challenges in a few ways:
* Choosing CommonMark
* Defining some additional, backwards-compatible with regular Markdown semantics. If you don't use them, you won't get as nice of an output in some cases, but if you do, stuff is a lot nicer. This includes things like "Show an icon to indicate that this does not compile" or "run this code sample as a test" or "this is a summary line and then this is a body."
* Writing Markdown to other format compilers. The Rust book (540 pages for its first printing) was written 100% in Markdown. Our editors don't use Markdown, they use Word. Carol, my co-author, wrote a DOCX to Markdown compiler in XSLT[1]. We write Markdown, compile it to HTML, concatenate it all into one big document, and send it to them. They open it in Word, they leave comments, we take the resulting DOCX, compile it back to Markdown, and address things.
[1]: https://github.com/rust-lang/book/blob/master/tools/docx-to-...
I've written every kind of documentation in Markdown, and it's not a panacea, but it does work. I'll talk about the article's points first, though:
> Lack of specification
https://commonmark.org/. It's not perfect, but GFM and it are (slowly) unifying. Pick one, document that that's the one you support, and you're done.
> Flavors
See answer 1.
> Lack of Extensibility
While it does not have an extension system, that doesn't mean that you can't do it. As long as you only add things, you should be good to go. Most things you'd want that aren't in the spec proper have some sort of existing extension that will solve your problems.
This is not ideal, but it's also not insurmountable. This is the only true negative I agree with on this list, I just don't think it's the end of the world.
> Lack of Semantic Meaning.
While this is true in a sense, at the same time, CommonMark lets you put any string on a code fence, which means that you can add whatever sematnic you'd like.
> Markdown is now dependent on specific HTML classes, and page design
No more dependent on those classes than on whatever other semantic marker you were trying to do, and if you want to change them, do what you'd have to do with the semantic: configure your tooling to put out something else.
> Document content is no longer portable to other output formats
This problem would still exist if semantics were there; someone has to write the mapping.
> Conversion to other markup tools and page designs becomes much harder
I disagree, but there's also no justification, so it's hard to respond.
> Lock-In and Lack of Portability.
This is a non-issue in practice. It's just like any other format.
-------------------------------------
All of Rust's documentation is in Markdown. We've overcome these challenges in a few ways:
* Choosing CommonMark
* Defining some additional, backwards-compatible with regular Markdown semantics. If you don't use them, you won't get as nice of an output in some cases, but if you do, stuff is a lot nicer. This includes things like "Show an icon to indicate that this does not compile" or "run this code sample as a test" or "this is a summary line and then this is a body."
* Writing Markdown to other format compilers. The Rust book (540 pages for its first printing) was written 100% in Markdown. Our editors don't use Markdown, they use Word. Carol, my co-author, wrote a DOCX to Markdown compiler in XSLT[1]. We write Markdown, compile it to HTML, concatenate it all into one big document, and send it to them. They open it in Word, they leave comments, we take the resulting DOCX, compile it back to Markdown, and address things.
[1]: https://github.com/rust-lang/book/blob/master/tools/docx-to-...
If Markdown gets you the features you need, go for it. In my experience, it usually doesn't, except for the simplest projects. So I use reStructuredText, so that I don't have to deal with someone telling me I need to use DITA because the documentation is too low-fidelity.
Every GitHub repository with a `readme.md` file formatted with Markdown would disagree and proves otherwise.
Markdown solves 90% of the problem, which is more than good enough.
Markdown solves 90% of the problem, which is more than good enough.
Sorry, but no. Documentation should be small, portable and easy to read on any device, even if you don't have a graphical interface. Hence the reason why markdown succeeded. It is meant to be simple to learn, simple to write, simple to understand. And you can teach a non-tech person how to use it in a matter of 15 minutes. And it is nearly perfect for wikis.
That is no to say that in some cases you may find it lacking. I have and in those cases I always resort to restructuredtext. My biggest argument in favour of restructuredtext is the scikit-lerarn documentation. It covers a variety of complex topics and everything has come out perfect. Annoyingly it hasn't been very successful outside the python world but as an example I am currently using it for documentation on a project which(for the time being at least) won't include any python code.
That is no to say that in some cases you may find it lacking. I have and in those cases I always resort to restructuredtext. My biggest argument in favour of restructuredtext is the scikit-lerarn documentation. It covers a variety of complex topics and everything has come out perfect. Annoyingly it hasn't been very successful outside the python world but as an example I am currently using it for documentation on a project which(for the time being at least) won't include any python code.
All the benefits OP sees for AsciiDoc are negatives in my book. The primary benefit to Markdown (in my opinion) is that it is always plain human readable text. I don't have to worry that there will still be a program in the future that knows what
include::source_code.js []
function multiply(num1,num2) { var result = num1 * num2; return result; }
means or how to process it.
I can read markdown easily without having to run it through a program. Of course it is nice to run it through a program to change bold text to <b>bold text</b>, but that is entirely optional.
I keep all my notes and other writings in markdown because I know that even if all markdown parsers ceased to exist and another one was never written, I would still be able to read everything with no trouble.
include::source_code.js []
function multiply(num1,num2) { var result = num1 * num2; return result; }
means or how to process it.
I can read markdown easily without having to run it through a program. Of course it is nice to run it through a program to change bold text to <b>bold text</b>, but that is entirely optional.
I keep all my notes and other writings in markdown because I know that even if all markdown parsers ceased to exist and another one was never written, I would still be able to read everything with no trouble.
To the author: perhaps you're an authoritarian manager, or a manque thereof. I don't know. But I'm pretty sure you're not the boss of the internet. So please drop the petulant imperative title.
I'm guessing the author doesn't like reStructuredText either.
Concurrent rebuttal thread: https://news.ycombinator.com/item?id=22677970
Edit: ah, the original post in this sequence was https://news.ycombinator.com/item?id=22675165. It set off the flamewar detector. (Apparently markdown does.) We've turned that penalty off, so it's back on the front page now.
Edit: ah, the original post in this sequence was https://news.ycombinator.com/item?id=22675165. It set off the flamewar detector. (Apparently markdown does.) We've turned that penalty off, so it's back on the front page now.
> As the result, the base Markdown syntax can have an extra set of features available only in a particular specification.
The big win of Markdown is that the source reads just fine, without conversion to html. The source itself is formatted, especially a monospace font. That makes it easy to write, since you can still easily attend to both content and formatting while writing it. It also makes it readable by folks in terminal or text editor. That also means that if your converter doesn't support some special feature, it will just leave it there and you can still just read it.
On the other hand, if as a reader or writer I have to go to some other part of the document or some entirely separate file, e.g. to find out the value of an attribute or edit an included external code snippet, that really interrupts the process. Same for computing if-else clauses.
The big win of Markdown is that the source reads just fine, without conversion to html. The source itself is formatted, especially a monospace font. That makes it easy to write, since you can still easily attend to both content and formatting while writing it. It also makes it readable by folks in terminal or text editor. That also means that if your converter doesn't support some special feature, it will just leave it there and you can still just read it.
On the other hand, if as a reader or writer I have to go to some other part of the document or some entirely separate file, e.g. to find out the value of an attribute or edit an included external code snippet, that really interrupts the process. Same for computing if-else clauses.
Markdown actually doesn't have tables - they're only in extensions or if implemented in HTML: https://talk.commonmark.org/t/tables-in-pure-markdown/81
Your "headline" is just too general..especially for advertising asciidoc ... for sure there are use cases for both
If you do that kind of stuff with people, it would be called "racism" or "discrimination" ...not a good start ;-)
Why should anybody use asciidoc (over md) for a simple doc or user guide ... ? My customers wouldn't pay the premium, because there is no added value for them if I would "learn" asciidoc for these tasks.
And maybe next time better use a term like "I don't use..." people don't like to get told what they have to do. ;-))
If you do that kind of stuff with people, it would be called "racism" or "discrimination" ...not a good start ;-)
Why should anybody use asciidoc (over md) for a simple doc or user guide ... ? My customers wouldn't pay the premium, because there is no added value for them if I would "learn" asciidoc for these tasks.
And maybe next time better use a term like "I don't use..." people don't like to get told what they have to do. ;-))
https://en.wikipedia.org/wiki/Creole_(markup)
I remember ages ago someone went and did a review of markup DSLs and Creole was their winner IIRC.
I remember ages ago someone went and did a review of markup DSLs and Creole was their winner IIRC.
I wish there was a datastructure standard for the "AST" that mardown et. al. produce. (Maybe that's just HTML? I wonder what Pandoc's internal datastructure(s) for docs look like..?)
Is Docbook dead?
I see it mentioned here only as an output format, between HTML and PDF, which sounds strange because I don't know any way to view it without first converting it to something like HTML or PDF.
Docbook is a bit verbose, but highly semantic. I always liked the idea of Docbook, though I could never get it to work well. At best, you waste a lot of time installing and configuring a big slow chain of programs to get ugly HTML or PDF that's virtually impossible to adapt to the style of your webpage or book.
Today the docbook.org "Tools" tab only points to a couple of XSLT stylesheets, so it looks like they haven't improved since last I tried. It's one of those technologies that I say "I should learn that...", look at for a couple days, and then say "Maybe I'll check back in 5 or 10 years." Like XSLT.
I see it mentioned here only as an output format, between HTML and PDF, which sounds strange because I don't know any way to view it without first converting it to something like HTML or PDF.
Docbook is a bit verbose, but highly semantic. I always liked the idea of Docbook, though I could never get it to work well. At best, you waste a lot of time installing and configuring a big slow chain of programs to get ugly HTML or PDF that's virtually impossible to adapt to the style of your webpage or book.
Today the docbook.org "Tools" tab only points to a couple of XSLT stylesheets, so it looks like they haven't improved since last I tried. It's one of those technologies that I say "I should learn that...", look at for a couple days, and then say "Maybe I'll check back in 5 or 10 years." Like XSLT.
The arguments in this article are extremely weak.
First, yes, Gruber established the base specifications for Markdown back in 2004, but so many other people have added extensions on top of it. This is also a contradiction to the author's third point about there being a lack of extensibility. Pandoc has a really extensive Markdown syntax, as does Github. As far as I know, nobody has mucked around with the basic semantics.
Second, I would much rather be able to express things that aren't supported by my flavor of Markdown with HTML, which is a typesetting language at its core, than something like LaTeX, which is kind of a mess readability-wise. Additionally, the nice thing about HTML is that I can add CSS to it (for most rendering engines) and stylize it however I want).
That said, I agree that AsciiDoc isn't bad. I also liked emacs org-mode before I discovered Markdown.
First, yes, Gruber established the base specifications for Markdown back in 2004, but so many other people have added extensions on top of it. This is also a contradiction to the author's third point about there being a lack of extensibility. Pandoc has a really extensive Markdown syntax, as does Github. As far as I know, nobody has mucked around with the basic semantics.
Second, I would much rather be able to express things that aren't supported by my flavor of Markdown with HTML, which is a typesetting language at its core, than something like LaTeX, which is kind of a mess readability-wise. Additionally, the nice thing about HTML is that I can add CSS to it (for most rendering engines) and stylize it however I want).
That said, I agree that AsciiDoc isn't bad. I also liked emacs org-mode before I discovered Markdown.
I could be swayed, but I personally LIKE markdowns limited palette.