
Don't use markdown for documentation (2018) - splix
https://mister-gold.pro/posts/en/asciidoc-vs-markdown/
======
dang
Concurrent rebuttal thread:
[https://news.ycombinator.com/item?id=22677970](https://news.ycombinator.com/item?id=22677970)

Edit: ah, the original post in this sequence was
[https://news.ycombinator.com/item?id=22675165](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.

------
tristor
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.

~~~
seph-reed
> 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.

~~~
input_sh
You may be interested: [https://markdown-
here.com/features.html](https://markdown-here.com/features.html)

------
untog
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.

~~~
Symbiote
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...](https://github.com/KiCad/kicad-
doc/blob/master/src/getting_started_in_kicad/getting_started_in_kicad.adoc)

~~~
dwohnitmok
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.

------
svat
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](https://news.ycombinator.com/item?id=22675165)
— but according to its author
([https://twitter.com/hillelogram/status/1242502542212333576](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.

~~~
balfirevic
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.

~~~
battery_cowboy
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.

------
castillar76
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!).

------
keithwhor
> 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
"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
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
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.

------
filmgirlcw
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.

------
indymike
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.

------
axegon_
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.

------
irrational
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.

------
tombert
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.".

~~~
afarrell
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.

~~~
tombert
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.

------
edgarvaldes
>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.

------
splix
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.

------
paxys
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.

------
wintorez
No. Markdown is the sweet spot between plain-text and HTML, and that makes it
perfect for the task.

------
mch82
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.

------
stared
(Discussion-wise, the link is a dupe.)

A recent discussion thread on exactly the same topic:
[https://news.ycombinator.com/item?id=22675165](https://news.ycombinator.com/item?id=22675165)

------
therealmarv
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](https://github.com/tompollard/phd_thesis_markdown)

------
ken
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.

------
silasdavis
Weak semantics are a feature not a bug. Flavour standardisation is happening
(see [https://commonmark.org/](https://commonmark.org/)). The ability to abuse
notation a little to provide extensions is actually rather practical. Things
like templating, inline code, slides.

------
CuddleBunny
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!"

------
zdw
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](https://talk.commonmark.org/t/tables-in-pure-markdown/81)

------
uk_programmer
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.

------
neya
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.

------
bgorman
Org-mode is another powerful alternative to markdown. Github can render org-
mode documentation.

------
oftenwrong
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](http://example.com)).

In plain text, a line break is a line break.

Swap out your README.md for a README today!

------
meesterdude
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.

------
pnathan
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.

------
peschu
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. ;-))

------
nunez
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.

------
jmilloy
> 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.

------
cmckn
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.

------
enobrev
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.

------
crispinb
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.

------
smitty1e
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.

------
coldacid
I don't mind giving up Markdown for writing docs, but only if we all agree to
use Org-mode text instead.

------
nemetroid
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.

------
ironmagma
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.

~~~
afarrell
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>)
    

```

~~~
Macha
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.

------
carapace
[https://en.wikipedia.org/wiki/Creole_(markup)](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.

------
carapace
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..?)

------
KuhlMensch
Hm. The fact that markdown doesn't understand its own structure is a bit
annoying - but anchor tags are easy.

I could be swayed, but I personally LIKE markdowns limited palette.

------
reyan
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.

------
natch
The ifdef and ifeval features are nice, but I would not take advice about
document formatting from anyone who uses full justification layout.

------
drtyolmck
no

------
bionhoward
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

------
grliga
As long as the converted html is provided for the reader, markdown is perfect

------
steveklabnik
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/](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-...](https://github.com/rust-lang/book/blob/master/tools/docx-to-md.xsl)

------
freeopinion
I'm guessing the author doesn't like reStructuredText either.

------
mattl
Both alternatives look like garbage as plain text.

------
bediger4000
At least he's not vehemently advocating Word.

------
xapata
rST fits all the goals of both sides of this argument. Reads well in original
format, supports more features than Markdown.

------
thomasdd
> Note: I Love Markdown

------
kempbellt
Don't tell me what to do.

Also, I like markdown.

------
lipis
No way!

------
jerng
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

