The Problem

I love using Markdown to write questions, answers, posts, comments, etc. That being said, I am a very technical, detail-oriented, programmer type. However, I am working on a CMS of sorts to be used by non-technical folks. I am using Markdown for this, but I'm becoming increasingly worried that it will be too technical for the users. It works great for users of Stack Overflow but let's face it. We love to learn new languages. Users hate new things.


You and I both know (because we're good programmers) that WYSIWYG editors produce a jumbled mess of non-semantic markup. (If you don't know this, check out this excellent article by David Demaree and then you will.) What you and I don't know is how users feel about it. Programmers are terrible when it comes to guessing at users' pain points.

The Question

Can Markdown simultaneously solve the need for clean markup and not be grating for non-technical users?


After a year of watching users with our Markdown editor, and dealing with the HTML generated on the server-side, I am firmly convinced that Markdown can be used by non-technical users of varying skill levels. Users have had no trouble getting the basic syntax (since it already resembles email conventions) and with some helpful tips (look at Ellie's answer below for some specifics) they can get the more advanced syntax very quickly.

  • 3
    I love markdown, i hate certain 4 space indenting rules though that quickly turn editing a pain just as well in Markdown as in UBBcode.
    – Martijn Laarman
    Jan 6, 2009 at 14:47
  • Would it be better if you could use TAB for indenting? ...or is this not the issue you're describing?
    – brad
    Jan 6, 2009 at 14:49
  • Nah trapping <tab> in the editbox is even worse. Whenever i need to reply with nested lists in Markdown or UBBCode i get a bit fidgety and annoyed due to (usually) too small textareas and no (or postback) preview functionality :). 4 spaces and space enter rules are hard to notice UBBCode wins there.
    – Martijn Laarman
    Jan 6, 2009 at 15:01
  • Tab on the web = next input control (and shift+tab = previous). It's best to avoid overriding expected browser behaviour.
    – Keith
    Jan 6, 2009 at 15:12
  • 1
    I like the irony of the linked article from David Demaree "...you’ll probably be horrified to see the HTML code that has been computer-generated.."
    – MSalters
    Jan 6, 2009 at 16:03

10 Answers 10


I know I'm coming to this thread rather late, but I actually have run usability tests comparing a WYSIWYG editor (iWeb) to a non-WYSIWYG editor based mostly on markdown.

Here's what I've found that users struggle with when using markdown:

  • Tags that require character-level precision. For example, a user's inclination is to put a space between the square brackets and parentheses when making a link--but that doesn't work. Likewise, lists only work when there is a space after the asterisk or dash.
  • They get paragraphs fine, but users are often inclined to use a single linebreak (when formatting an address, for example) and these are ignored if you don't add two spaces to the line before. Not intuitive, and those two spaces are invisible.
  • More complicated tags, like for links and images, slow them down more than simple ones (like for strong and em)--but they can eventually get it if there's a helpful guide.
  • Users are often not confident that X will work or unsure of exactly what it will do.
  • Users don't always understand paths, directories, files, file extensions, URLs, etc. This makes making links and images difficult.

Here's what I've found helps:

  • Provide a clear and explicit guide to markdown
  • Tell them they are using a markup language
  • Style the text field so that it doesn't look like a WYSIWYG field (eg: use a fixed width font)
  • Consider syntax highlighting
  • Be clear about any situations that are counter-intuitive or require attention to detail
  • Provide a preview option (it doesn't have to be real-time, but it must be easy and unobtrusive)
  • Depending on the application, consider tweaking it slightly (like allowing a URL like www.example.com and adding http:// automatically)
  • At the very least, provide buttons for the more complicated tags like images and links. It's trivially easy for the programmer to make a little dialog box that asks for the URL and the link text and inserts the code automatically. Consider making the language easy to understand. Instead of asking for the URL, ask "What web address would you like to link to?" Take a look at how Javascript WYSIWYG editors use non-technical language here.
  • Give them an idea of why this is important. Explain that semantics and presentation are separated in web design, and that computers generate bad code--so they are helping the program understand the semantic structure of the document.

I was surprised to find that people were mostly getting it, with no guidance from me and just a short guide to the markup language. In a study with 22 total users, the average satisfaction was slightly lower for iWeb than with my application.

If you're talking about an entire WYSIWYG web design program, not just a little widget for text entry--they're not as usable as you'd think. There are so many little details, and so much can go wrong, even when the interaction is supposed to be intuitive.

Caveat: my participants were all college students of varying technical skill levels, but they were all more tech-savvy than the average user. They were also being compensated for their time, which may account for their interest in the task.

Edit Almost all of the above issues have been improved by the stuff in the second list. The only one I'm still really struggling with is the single linebreak problem.

  • 1
    Nice to see work like this. can you publish the details?
    – AJ01
    Nov 30, 2009 at 11:51
  • 5
    Great analysis Ellie! I have found many of these things out as well. As for the linebreak problem, I think the standard markdown implementation is flawed. We have implemented our own parser for this reason and changed some of the default behavior. For instance, we allow space inside of link/image brackets and we create a new paragraph for each linebreak. This has gotten us wonderful results.
    – brad
    Nov 30, 2009 at 16:51
  • @AJ It's for an undergraduate research project that I'm in the middle of. I'm currently writing about it and plan to submit it to a conference, but at the very least I'll make a webpage for the project when I'm done.
    – Ellie P.
    Nov 30, 2009 at 22:30
  • @brad I've already implemented my own markdown customizations for some things, and I've been toying with the idea of implementing the two you mentioned. I'm glad to hear it worked for you--I'll give it a try.
    – Ellie P.
    Nov 30, 2009 at 22:32
  • 1
    To clarify the single linebreak issue: there's nothing wrong with how it's implemented in markdown because programmers and web designers often use text-editors that do not auto-wrap text (thus introducing lots of presentational newlines.) Customizing markdown so that it does not require two spaces before a single linebreak would only work if the text doesn't have "non-semantic" linebreaks. In my case, I am in control of the text editor being used, so I will try implementing the change.
    – Ellie P.
    Nov 30, 2009 at 22:39

Unfortunately not.

When you say non-technical: there's a huge difference between non-programmer and 90% of the non-technical users out there.

A surprising number of users (I think it's around a third of everyone on the web) can't scan text - they will use their finger on a page to read and will lose their place if forced to scroll.

These users will struggle with even simple WYSIWYG, never mind any sort of markup.

A good article on the issue is: https://www.nngroup.com/articles/writing-for-lower-literacy-users/

I'd recommend taking a look at that site for most usability research like this.

If a user is struggling to understand the I-bar and caret they're never going to understand any sort of meta-information.

  • 1
    That is a very saddening article. "use text aimed at a 6th grade reading level on the homepage" But do I even care about these types of users considering they probably won't contribute much anyway?
    – brad
    Jan 6, 2009 at 15:05
  • 3
    Depends on what you're doing - these aren't 'stupid' users - just low literacy. If literacy level is not directly linked then you may be missing input (and site use) from practically skilled users. Some are actually high literacy, but very low computer confidence (like many silver-surfers).
    – Keith
    Jan 6, 2009 at 15:10
  • 9
    Seriously - low computer competence != stupid, any more than dyslexia does. I don't know what the OP is developing, but any sort of markup will completely exclude about 1/3 and seriously deter another 1/3 of the users with little or no word processing skills.
    – Keith
    Jan 6, 2009 at 15:44
  • 1
    Any mark-up (i.e. bold here, italic there) is "meta-information" - extra information about how to display the text.
    – Keith
    Jan 7, 2009 at 16:56
  • 1
    Ok, if you look at it that way. :) But why do the users need to understand it? If they don't understand it they just won't use it, so I really don't understand the question either. Jan 7, 2009 at 20:33

On a largeish project, I thought textile would be simple enough for non technical users. It turns out I was wrong, and my clients just couldn't cope with it at all. The problem eventually became so severe that they replaced my whole system. The system I spent 8 months building.

Live and learn. To be honest, I don't think Markdown is easy enough for TECHNICAL users. The problem is it gets applied to content entry forms without informing the user that it's going to be filtered through markdown. Text gets mangled, and there's no way to know what happened unless your eyes are sharp enough to notice some tiny note somewhere.

There's a dozen of these different markupish languages with slightly differing semantics, and each one is a whole new set of things to learn. You come to a comment form, and who the hell knows what's going to happen? is it textile, markdown, bbcode, how on earth do I make a link? It's a mess.

Well there you go. Two data points. A client couldn't cope with it. I can't cope with it. The only reason I have any idea what's going on here on stackoverflow is the gui buttons. and the realtime preview.

@tj111 a cheat sheet helps me, but it didn't seem to help anyone else. I'd even pointed it out numerous times, but it just didn't seem to take hold. I ended up doing all the textile myself.

  • 2
    I'd second the client thing - our client (made up of HR professionals) turned out against any sort of mark-up based rich text too.
    – Keith
    Jan 7, 2009 at 16:59
  • 5
    @Breton: +1 I agree when you say: I don't think Markdown is easy enough for TECHNICAL users. I think anyone could hardly say I'm not a technical user. I know how to use markup editors here on SO and also on any forums (bbcode), but it's still a FRUSTRATING WASTE OF TIME to always have to look at the preview of the post before submitting it even here on SO that the preview is updated at runtime. That said, it's also true that there is no WYSIWYG able to genarate code that is not just an horrible mess. Aug 26, 2011 at 12:17

Yes, I think it can.

What I have personally found very helpful:

  • Having a preview and allowing user to see what the resulting text will look like

  • Having a short help section explaining the basic markdown elements

  • 4
    Good point on the preview. That's one thing I really wish more sites did, and something I'm very grateful on SO :-)
    – Jon Cage
    Jan 6, 2009 at 14:48

Define 'non-technical user' because in my experience, it's more of a sliding scale than technical or non-technical. I don't think it's beyond most intelligent humans to get to grips with markdown, but it depends on your audience as to how much they will love or hate it.

As a general approach, I would use it but add buttons which allow less techy people to fill in the details in a way they're more likely to understand (give them prompts). If you do this, but keep the result visible, you'll teach them how to stop using the buttons too :-)

[EDIT] If the users are in a hurry and have little or no word processing skills, I would be suprised if they bothered with anything but plain text. If you'd never used word (or something similar), chances are you'd normally just use a pen so underlining and font size is likely the most advanced formatting you'd have experience with. In which case, I'd personally drop the idea of using markup. Depends a bit on what you're building though I should think as to how critical this will be.

  • You make a good point. I wasn't clear on the definition of a technical user. Thanks!
    – brad
    Jan 6, 2009 at 14:48
  • The comment about them using a pen reminds me of the fountain pen forum I frequent. These are people (20k), many old, who explicitly use an archaic writing instrument almost exclusively, yet they seem to have no trouble using the forum... I think basic computer literacy is a reasonable expectation.
    – rmeador
    Jan 6, 2009 at 15:33
  • I agree that expecting someone who'll be using CMS is likely to have reasonable computer literacy, but that was not what brad listed in his definition of his non-technical users.
    – Jon Cage
    Jan 6, 2009 at 16:24

I think everyone is guessing again. As brad suggests, our guesses are likely to be way off.

The only way to be sure is to run usability tests.

Does anyone have any information about usability tests which have been done to look at using markdown?

(Or something similar e.g. Wikimedia?)

The closest thing I've found is a screencast comparing the usability of markdown vs. a WYSIWYG editor. It's not a usability test, however.

  • 1
    Beat me to it. A quick search of Google Scholar doesn't bring anything up.
    – Jason Baker
    Jan 6, 2009 at 15:14
  • 2
    I did one for an academic project (described here: stackoverflow.com/questions/416766/…) Still a work in progress. Not published yet...
    – Ellie P.
    Nov 29, 2009 at 4:51

Not a direct answer, but might be helpful: Look at LyX. It's a almost-WYSIWYG editor that produces (something very close to) LaTeX. I used it to introduce my mother to LaTeX and she loves it, even 'though she's got no technical background whatsoever.

I think it is a great example how you can produce a usable editor for a well-designed technical syntax.


If you are worried about WYSIWYG editors producing jumbled HTML, check out MooEditable, a project I work on to produce standard, valid HTML no matter what the browser (it's a MooTools plugin).

Back to the question at hand though, Markdown is friendly enough for the majority of users, as long as you provide some sort of "cheat sheet" that's visible from the text area. And also link to a more in-depth description in a help link, maybe even a tutorial, for those who are a little slower with computers and technology.


Unless your users need tables...then you'd need some kind of weird WYSIWYG + (WYSIWYM + preview) hybrid, which may not exist.

  • 1
    LoL, and hopefully never will! Tables in the hands of users? shivers
    – brad
    Jan 6, 2009 at 15:49
  • My users happen to have the odd bit of tabular data for their documents.
    – Kev
    Jan 9, 2009 at 22:21
  • 2
    Here we are in 2016, and my Baby-Boomer father who has difficulty simply signing in to Google sites (analytics, etc) still manages a massive list of products by using an older version of TinyMCE and editing tabular data that is copy+pasted in from Excel. By some sort of miracle of Gaia, he manages to never break the table tags and data is presented accurately. I have no idea how this can be so.
    – pspahn
    Apr 20, 2016 at 18:13

I think Markdown is worth it.

If the formatting syntax (like asterisks, etc) is too much for them, Markdown will at least handle paragraphs they way they expect.

Even the least tech-savvy user will hit return twice to create a paragraph, and Markdown will do the right thing with that. Even if they don't take advantage of anything else, handling paragraphs will make for MUCH more readable content than enormous blocks of text.

Not the answer you're looking for? Browse other questions tagged or ask your own question.