If you’ve ever written technical documentation to use online, you probably started out by creating it directly in HTML (hypertext markup language), so you could drop it directly into your website.

You may have used various HTML editors that gave you a real-time but not entirely precise preview, but you’ll have spent plenty of time wrangling with one of HTML’s most annoying characteristics, namely that the so-called “markup” is bulky, and hard to read, and easy to mistype.

To make a word bold, for example, you end up with the clumsy input <strong>bold</strong>.

To create lists you need to add special tags at the start and end of the list, and then special tags at the start and end of each item, which makes proofreading harder than it needs to be, like this…

    <li><strong>Design.</strong> <em>Do this first.</em></li>
    <li><strong>Code.</strong> <em>Then hack away.</em></li>
    <li><strong>Test.</strong> <em>And finally check if works</em>.</li>

…just to get this:

  1. Design. Do this first.
  2. Code. Then hack away.
  3. Test. And finally check if works.

Worse, your marked-up text only works on websites, or in browser-like windows, so you need a plethora of conversion tools anyway if you also want to render your documents into plain ASCII, or some other widely-used format such as PDF, RTF or DOCX.

Worst, not all HTML markup can readily be converted into other formats, so you need to remember which HTML constructs you’re not allowed to use, in case you end up with a document where most, but not all, of the content can be rendered in other types of file.