5 ms·
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
by steveklabnik 7y ago
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-md.xsl https://github.com/rust-lang/book/blob/master/tools/docx-to-...