(However it’s ridiculous how some people keep insisting that WYSIWYG is dead. Yeah right.)
So inevitably I started searching the lazyweb for the best markup language. In 2006 I was part of the Ubuntu documentation team for a while and helped with the DocBook/XML-based workflow to generate documentation. We used to write that in plain VIM and it sucked badly to maintain the XML sources but there were no serious tools to manage DocBook back then. A few years later I used to write documentation in Restructured Text (RST) format. Although I often mistyped the syntax it worked pretty well. Sphinx provided a good framework with automatic references to my Python code.
Then out of curiosity (and the death of my favority Python-based “Pylons” web framework) I started to learn Ruby. Sphinx did not really work for Ruby code so I needed something else. And as I was working with GitHub I had to learn Markdown syntax. It was very basic and seemed to be a thin layer of markup upon HTML. Markdown looked similar to Restructured Text and I wondered why someone reinvented the wheel. But only today I start to realize how confusing Markdown has become. As Markdown was very limited someone came up with Markdown Extended and added semantics. GitHub found that neither Markdown nor Markdown Extended suited their needs to they use “GitHub flavored Markdown”. So did StackOverflow. Three different kinds of Markdown? That can’t be good.
Next I was looking for a half-decent editor. Some nerds insisted that Sublime Text is the only good editor because it has extensive Markdown support. I don’t mean to bash Sublime Text – I have bought it myself. But it’s not any more capable than Komodo Edit and its Markdown support is hardly better than VIM’s.
At the end of the day I learned that there are several flavors of Markdown that are all differently limited. What puzzles me is that the majority of programmers seems to have jumped on the Markdown bandwagon and some claim it’s the best markup language for documentation because the majority of nerds use it nowadays. I’m sorry – I don’t recognize why I should rely on it.