The varying appeal of wikitext and other simple markup

November 21, 2012

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

Comments on this page:

From at 2012-11-21 06:08:43:

I've come to use wikitext as a write-only language, translating it to HTML and then editing the result if I need to change it. What I hate about writing HTML is a) the tedious boilerplate one must hammer out, and - this is really silly, but I'm not really kidding - b) I hate holding down shift to type angle brackets.

- Smarry

By trs80 at 2012-11-21 08:15:06:

There's also the third option - HTML but with a contentEditable wrapper. Definitely the most novice-friendly, it also produces the ugliest HTML if you ever need to edit it.

From at 2012-11-21 12:46:27:

Markdown appeals to me foremost for reasons other than its popularity – which reasons I believe its wide adoption specifically derives from, rather than just being an accident. Namely, two aspects:

  1. For the most part, you can just type away without learning anything and much of the time, what comes out will be what you intended. I.e. it’s mainly a codification of very common conventions.

    (It has one serious flaw in that respect: it regards intra-word underscores as epmhasis markers. Gruber declared this a bug and an intent to fix it, but never actually did. The big sites that support Markdown all have.)

    This helps rare and novice users.

  2. It is just HTML! You can type HTML and it will come out verbatim. It’s not really a separate markup language (simple or not) so much as a shorthand notation for HTML.

    So you don’t have to use Markdown’s syntax instead of HTML. Forget how to write a link in Markdown? Just write it using HTML syntax. Will work either way.

    People don’t overlook this as a great feature, but I think they still don’t appreciate it enough. It’s the singular most brilliant decision in the design of the markup, and what puts Markdown in a class of its own and separates it from the would-be competition.

And I think these reasons address the concerns of your coworkers, should you choose to use Markdown.

Aristotle Pagaltzis

Written on 21 November 2012.
« Where my Firefox performance problem seems to be
Optional features are in practice not optional to understand »

Page tools: View Source, View Normal, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Wed Nov 21 01:24:55 2012
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.