After letting the issue sit for a while, we've recently started thinking about our wiki trap again (partly because the support period for the OS our wiki is running on is rapidly running out). One of the questions for any replacement is whether we'll write the content in straight HTML or in some simple markup scheme. Having this question on my mind has made me think about the varying and relative appeal of wikitext to different people. For this, let's break people up into three different groups, which I will call frequent authors, genuine beginners, and moderate authors.

For frequent authors I continue to believe what I've written before, that simple markup languages reduce the friction of creating raw HTML and enable you to focus your effort on what matters. This is the case I fall into with Wandering Thoughts and using a simple markup language has been extremely useful for me (most of my entries have very little besides plain text). While you do have to learn the potentially special-purpose (simple) markup language, the long term time savings and reduced friction make it worth it in the same way that heavy users of anything should get good interfaces even if they're non-standard.

(In fact optimized simple markup languages are exactly this if you take a somewhat expansive view of 'interface'.)

For genuine beginners with no real experience with HTML, a good simple markup language is probably easier to immediately produce content in without a big hassle and learning experience. This is not necessarily because simple markup is hugely simpler (HTML is pretty simple, really) but because simple markup gives you far fewer ways of blowing your foot off than HTML does. Put a < in, leave a > out, forget an ending element, and all sorts of unpleasant things can happen to your HTML content. A well designed simple markup language does not let you do these things or limits the damage that they do, resulting in a faster and less frustrating authoring experience.

(My feeling is that this is pretty dependent on the markup language being readable and memorable. For all its flaws and irritation, HTML is good this way; you are not going to mistake <b> for <i> in the way that you may confuse, say, `` and ```` (quick, how many `'s is that?).)

For moderate authors, especially people who produce stuff across many sites, your simple markup probably sucks. These people already know HTML and they aren't going to be writing enough for you to make learning your simple markup language a time win, especially if they have to re-learn it almost every time they write more because it's been a relatively long time since they last used it. You can reduce the advantage of HTML by making your simple markup widely used, so learning it once pays off not just on your site but also on other sites (but this only works if your authors also author stuff on those other sites).

(Hence part of the attraction of Markdown (in its small variants). If a bunch of significant sites and software all agree on Markdown, it becomes more of a win for everyone.)

Having written all of this down, I've now come around to the views of my co-workers (they like HTML, I like simple markup). Our situation with our documentation is most like the moderate authors situation; we all already know HTML and we are just not going to be writing documentation all that often. While I reflexively like simple markup it's hard to see how it would be a win for saving time and reducing irritation. The possible way out would be to persuade my co-workers that they're going to want to know Markdown in the future anyways, but I'm not sure that that's true in practice.

(There are other reasons to use simple markup besides the convenience of your authors, but that's another blog entry.)