The other syntaxes mentioned will not be mainstream enough to gain critical mass for some time, if at all. Markdown, for many projects, is literally plain text with some added frills for headings, lists, and code blocks.
Yes, adding a code snippet inside a table cell inside a list can be a pain-inducing experience (especially until CommonMark settles things down a bit)... but that's about .05% of anything I've ever written, and for those particular instances, I fall back to HTML, which is completely compliant and much less ambiguous.
For myself, and for most of the projects I've worked with and maintained, you need documentation to be dead simple in syntax, and requiring a syntax with even less adoption than Markdown is an easy way to cause users who would've otherwise contributed doc fixes and updates behind.
Welcome to the BDSM club.
Big Document in Shitty Markup.
Oh, and I have used homebrew markdown preprocessors to write books (e.g. http://t3x.org/s9fes/edoc.html). Great fun!
And by the way, this is actually installed as a man page on target systems.
Most of my struggles were in the area of halfway decent HTML conversion. To that end, I started with a very hacky C program calld man2html, which actually contains a mini-troff implementation, and improved it quite a bit. I cloned that program here:
This had numerous issues, among the main ones being not handling loops and conditionals and so on for complex macros.
I still do quite a bit of post-processing on the output of this program, still, to do things like re-arrange its order, add internal hyper-links, and create a Java-scripted table of contents:
(Almost the same URL as before, s/pdf/html/).
That post-processing is done by:
I don't like the approaches you have to take in troff for defining multiple ways of doing the same thing, based on whether it is juxtaposed to something else or followed by whitespace. This is fundamentally broken.
For instance if you want foobar such that foo is italic, but bar is regular, you have to use .IR foo bar, rather than the .I macro. I'm sorry, but a markup language should have the scoping/delimiting wherewithal not to have to do stupid things like this.
I have a more or less fixed (non-growing) set of such redundant macros in the document and so it doesn't bother me that much any more.
> I'm sorry, but a markup language should have the scoping/delimiting wherewithal not to have to do stupid things like this.
(btw, mdoc has this and is widely supported, having been around for about 2 decades... having discovered it, I'll never write a manpage in man again)
"mandoc" is the name of a newer troff/nroff macro package for writing man pages which replaced one called "man". (nroff -man versus nroff -mandoc).
The renamed "mandoc" project provides a processor which understands a "mdoc" language, a set of macros used on BSD Unixes. It's not a full processor for the roff language. The mdoc language has macros that resemble mandoc, like .SH, .TH and others.
In the TXR man-page-like reference manual, I'm using real roff macros (some of which output mandoc macros as their target, in the original sense of mandoc).
I don't think these macros could run in under the mandoc system, where you have to use a canned repertoire of macros.
For instance, I have a macro like this.
.coNP Functions @, boundp @, fboundp and @ mboundp
Another complicated thing:
.mets (replace-list < list < item-sequence >> [ from <> [ to ]])
When you render this with a man reader, the macro puts out angle-bracket notation, exactly like this:
(replace-list <list> <item-sequence> [<from> [<to>]])
It has served me well, though :)
And I disagree about the portability. Write Pandoc-compatible markdown and you can convert it to just about any format under the planet. I love that I can write in Markdown, then quickly create a word document to send around the office for comments - whatever anybody says about Word, the track changes and review functions both useful and defacto standards in most offices.
Or - I should say, it infers structure from the sorts of things people did as a matter of course back when we had a network culture based on sending each other blobs of text via email or Usenet. I'm sure the original author of Markdown.pl was not intending to design a new structured document language at all, and simply wanted to pretty-up some plain text files for display on the Web. The structure was already there, the conventions were already in common use, and Markdown.pl was just one strategy for doing something useful with them.
I think it's easy to get people to use Markdown because it doesn't feel like writing in code, and it doesn't feel like writing in code because it's basically just the sort of thing we all did all the time before the web took over.
Ironically, then, I think it actually will make Markdown less useful to build it up as a rigidly specified uniform document protocol offering sophisticated formatting features. There's certainly value in having the various makers of tools doing this job work together toward a common understanding of the patterns people like to use, but it's far less important whether someone uses triple-tickmarks for quoting or four-space-indentation for quoting or whatever, so long as the tool can recognize that they are doing something, take a reasonable guess at what that might be, and then offer a simple way to correct that guess later if the user is particularly concerned about the way the text is being rendered.
but the problems arise because different markdown flavors
recognize different types of "common understanding of the
patterns people like to use", so misunderstanding happens.
RST, used by Sphinx, isn't quite as easy to write or to read. There are plenty of gotchas. RST adds friction.
Using Sphinx also requires you to setup and configure Sphinx for your project - even more friction early on.
The world is far better for having Markdown, and it's the right choice for most projects.
However, there is indeed a place for more complicated projects to take on the workload of a more complicated documentation system so that they can help user and developers better. Django's amazing documentation is an example of this, and a major reason for the success of the project.
What gotchas are you thinking about?
> Using Sphinx also requires you to setup and configure Sphinx for your project - even more friction early on.
You can perfectly well RST without Sphinx, it depends what you want to use it for. Obviously, if you want to use for Sphinx, you need Sphinx. But otherwise, you can perfectly well use rst2pdf or rst2html with a standard RST document.
The format for RST/Sphinx code blocks is to type two periods, a space, the word "code-block", then two colons, then exactly two new lines, and at last you can write your code. Indented with four spaces. Also, you have to make sure there is a blank line between that "code-block" magic line and your preceding text. In practice, I usually manage to screw some part of this up.
The extra complexity and cognitive load makes it much harder for a developer to just write thoughts.
You can make your own directives which can optionally accept key/value parameters. This is technically superior to slapping blobs of HTML inside your Markdown, though I will concede that writing your own directives can be a bit tricky initially.
You can do anything you need to in RST, but there's just more friction involved.
The reason it's a double colon is because a single colon acts like a normal single colon (i.e., it's not interpreted in any way), which is sometimes what you want (i.e., not every indented block is a code block).
I'm sorry but I just can't sympathize with any of the complaints leveled against Markdown. They are so minor and compared to the massive adoption of the common bits of Markdown, there's no chance I'd ever choose to write anything in any other markup than that just for those small annoyances.
I don't need custom extensibility when I can just add HTML. HTML is pretty good at markup, and it enhances the markdown in those rare occasions where what's provided seems too limited. The very last thing I'd want to do is literally write code as an extension to my markup language. The only code in my markdown is inside nice tidy code blocks for display purposes only.
I also use JSON for configuration, even though many have tried to convince the community that YAML or some other format is better. I pre-process my JSON to strip it of "non standard" comments, and I'm quite happy that I chose the by-far-defacto-standard there instead of going off the beaten path.
Techdocs have lots of cross references and other similar elements, their implementation in all markdown “standards” is really bad.
ReStructured text is much, much better.
It's not perfect or even ideal, by any means, but the other benefits of Markdown are more than enough to make up for the slight annoyances here.
I don't know about ReStructured text, but I can say that none of the examples in the OP swayed me that I'm missing anything of any import.
When I want to data serialization, I use JSON. It's incredibly easy to strip comments (and whitespace, for that matter) from extended JSON before transmitting and/or parsing. I wrote `JSON.minify(..)` for that years ago, and it's literally never been a problem for me since.
It also offers several advantages over JSON, in that it can also store and sanely represent relational data, has support for comments built into all YAML parsers, and it can be used to represent data structures that don't fall into the list/hash map paradigm.
Markdown is great for text content, not for formal documentation.
However, I always use markdown for all my OSS project documentation (READMEs, etc), and I do lots and lots of cross-referencing in that context. I use simple markdown links to named-section anchors.
It's a tiny bit more manual than I'd like, but it's never stopped me from doing technical documentation effectively.
assuming you're using one of the extended flavors.
but once it comes to the repurposing of your text,
switching to another flavor (for many good reasons)
will cause _many_ undesirable wrinkles to appear,
with a lot of them being rather difficult to find.
you might think this is a problem you'll never face.
i hope, for your sake, that you are right about that.
but don't say that you weren't warned.
because the experience is unhappy, and tedious.
and not what you'd expect from a "plain-text" format.
the _idea_ for markdown (which, by the way, should be
credited to ian feldman, with a follow-on by dean allen)
is spot-on. but the gruber realization is short-sighted.
(and, alas, stubbornly so, for absolutely no good reason.)
Markdown is a lot less verbose in my opinion than RST. It's not intentional, nor is it insurmountable, but little things like inline code, hyperlinks, defined subsection levels, and many more all add up to a bit of cognitive load that I don't need for all situations. When I'm writing quick notes for a meeting, or trying to jot down something, RST is a bit much. Which perhaps isn't what this article is really harping on.
But when my quick notes to myself about a project turn long-winded and become more of functional docs, it can be a pain to rewrite that into rst.
I do, however, tend to use RST when I sit down to write documentation for a project. I even tend to use it when documenting firmware and hardware portions of projects. This of course due to the so far poor handling of images in Markdown.
So like I said above, they are tools. One may be better suited to something than the other. But thus is the nature of tools. Use the right tool for the right job whenever possible.
It's also not that hard to move from Markdown to HTML incrementally, and generally unnecessary at all for long prose sections if you're not averse to having mixed HTML/Markdown source.
To me, RST smells very much like XML for people who don't want to admit they're writing XML. It superficially has the appearance of being "normal" plain text writing, but that illusion is fragile if you're not familiar with the language. IMO, it's akin to COBOL or SQL in that way.
I see the process as not being different from what's needed to do the writing - compiling notes and sketches and outlines into a coherent narrative.
If you just want to rewrite markdown into rst, "pandoc" will do the trick.
tl;dr: Markdown won.
I find this an unconvincing argument against Markdown per se. It's an argument against writing in the portable subset of Markdown, but why would anyone need to do that in their documentation? It isn't as if specific Markdown implementations are hard to come by, or that there is a context where it would be onerously hard to mandate a specific implementation.
Not to say that Markdown's fragmentation isn't a bad thing. It's annoying, especially when you do use different implementations in different pieces of software and you're trying to remember whether this version supports tables, say, and what the syntax might be.
> “Markdown” is the most commonly used markup language on the internet.
That'll be HTML. :) Not just being facetious. HTML is certainly an option for documentation, albeit not one I'd be totally happy with.
> You also can’t migrate Markdown easily to another markup language (Asciidoc or RST), because Pandoc and other conversion tools won’t support your flavor’s extensions.
Unless those flavours are Markdown Extra or Github or CommonMark, which pandoc does support. Pandoc also supports adding specific syntax extensions ad-hoc, as noted in its fine documentation. Although, I'd question why this would be an issue in practical terms.
For example, this:
Wouldn't that be HTML? :)
In general, I find org-mode about as easy as Markdown, but with support for things like cross-references that are sadly lacking in standard Markdown.
For manpages, I write mdoc directly. It's not hard. There are several great mdoc resources on http://bsd.lv
For reference material, I stick with either Pandoc or I use LaTeX (along with tex2page for generating HTML). Anything fairly small tends to get the Markdown treatment. If it's something I foresee will need to be split into multiple documents, I reach for LaTeX. Scribble is pretty nice, too, if you're dealing with Racket or Scheme.
Here's a quick cheat sheet... for the "why" of semantic styling your docs with something like .rst with directives makes for better overall integration.
Raising the barrier to entry to include learning complicated markup languages will chase them off completely.
I agree, it's far from perfect. But some documentation is better than none.
In the end I converted to Asciidoc, it does all I need, is readable and is not as python-centric as docutils (I use the python implementation but asciidoctor is ruby and there's even a chrome extension for live preview in the browser).
When you think you can learn a job (technical writer) by doing it bad rather than not doing it at all, you just take bad habits.
Serious technical documentation are structured. Pictures have captions, graphs have legends... It is cumbersome, it requires more data but that is the price to communicate (wait for it) INFORMATION to other humans.
Yes, writing structured documentation that can be easily used is part of what information technologies are. Structuring information from data.
Information is still analogic at the end and rst is just a typesetting chain designed for a domain specific kind of documents called technical documentation.
I am totally biased. I love readthedocs, I love POD, man pages, ISO documentations, IETF RFC, ASM papers, all kind of scientific papers, useful instructions that can help me do my job faster by following well known practices to be consistently readable without strain. And rst for this level of requirement is less a PITA than doing it conscientiously by hand or with markdown.
But I agree, I totally love the artistic freedom of markdown for writings too. But in a Museum, or as grafitis.
We talk about documentations right? Not art? So the title is accurate.
They aim to standardize the "markdown-like" formats into a single unified one. It's not done yet but it's certainly better than everyone for themselves.
It really is annoying though when I have to be careful about a convention that I'm using if I'm putting a README in BitBucket vs GitHub vs whatever else. Generally, if I'm just sticking to headers, lists, and quotes, I have no problem and everything works and I don't pay it another thought.
Just like you said, you just use $ or $$ to add LaTeX.
I am not arguing you should write a 600 page book with RMarkdown + LaTeX (just use LaTeX in that case), but it has worked well for me for technical reports and presentation.
This would be a good thing since any standard is better than the tower of babel we have now.
stick a certain version and do not change it.
the article is likely bias as writes states he works for read the docs.
On the other hand, creating a clickable image:
I'll never understand why clickable images are not the standard way the image renders once you type in:
I don't find that too bad.
I have done just fine with md
* 100 page Word document. 200 page Word document. Take your pick.
* 99% of it is clearly cut and pasted from somewhere else and contains information absolutely incorrect and irrelevant to the task at hand because it was accidentally included from the last document they cut and paste from, but people are afraid to remove it.
* Someone has manually typed in a few lines into a table (oooh, so THAT'S the temporary IP address of the server which will almost certainly change at a later date!) As it's buried in the document there's no way to extract, verify, or update it. It will be listed with a bunch of other IP addresses from the prior cut and paste, and if you get a server name in there, it's probably wrong too.
* They've also handed off the effort to any Architect, probably one of the people I see sitting in Visio day in day out drawing those diagrams of how a computer connects to the network. In a VM data centre. Where it's meaningless and has no connection to reality. And where the moment it gets turned on someone will install software that connects to 20 other servers in ways that will never be described let alone in this document let alone in a diagram.
* Now, take that, cut and paste the whole thing keeping it 90% intact, call it a "Controlled Document", add in the names of some people at the front and last edit dates (where every document starts at version 0.1 and stays there for its entire lifetime), and now you've got a process manual! Hundreds of them! Thousands of them! Don't worry they were all based on whatever kind of template the business was branded with from year to year so you can kind of tell which decade they were first created.
* And they'll be dumped in shares because whatever multi-million dollar document management system was never used by users before being bought and never ever ever works. If you're lucky they might have version numbers or edit dates which don't correspond internally but get you 90% of the way to finding which one is current.
I get to see those holy manuals in Enterprise every day. You have no idea how bad it is.
Pick a third party format apart from Markdown? Are you fucking serious? Enterprise doesn't buy fucking third party software and everything is locked down so that you can't run your own. This is Windows for fuck's sake and there aren't even decent free Markdown editors for it anyway.
I write MY personal documentation in Markdown and I do it in a plain text editor. If I ever need to draw a diagram or put in a picture then I know I've fucked up and to backtrack. It's just plain text. That's what Markdown is for. "Not portable" my arse. About the only thing I wish was easier is tables. And they'd probably be ASCII tables at that.
So yeah. The argument against Markdown is bullshit.
Situation: There are 14 competing standards
"14?! Ridiculous! We need to develop one universal standard that covers everyone's use cases.!"
Situation: There are 15 competing standards
The argument is that there are too many variations markdowns. Their solution? Another markdown.