Minimal IT logo and link to home page
Research, training, consultancy and software to reduce IT costs
Home | About | Newsletter | Contact
Previous | Next Printer friendly
2 February 2010

In praise of HTML

By Andrew Clifford

HTML should be the first choice for most documentation produced in IT.

Hypertext Markup Language (HTML) is intimately associated with the world wide web. This strong association can stop us seeing that HTML is of itself a powerful standard, and can be used very effectively for documents that are not intended for publication on the web.

The core of HTML is simple. It is based on plain text files, with some additional markup to control formatting. So, for example, if you want to emphasise something, you enclose it in a <em> .. </em> sequence. You can do this easily in a text editor. There are good, free tools for editing HTML such as Amaya.

We can, and should, use HTML more widely is system documentation, including design documents, specifications, test plans and operations documents. Almost universally, these are produced in Microsoft Word, but for these types of documentation HTML has a number of distinct advantages.

Anyone can read and write HTML documents. This might not sound much of an advantage since nearly everybody uses Microsoft Word. However, system documentation has to last for many years. There is already enough confusion around word processor document formats. Are you really confident that what you write in Word today will be usable in 15 years time?

If you need to publish the documentation widely, it is much easier to have HTML on an intranet server than to make a Windows file server available to everyone.

HTML works well with source code management products, which are routinely used in systems development. HTML is compact, and it is feasible to retain a complete history of old versions of documentation alongside the versions of code that it documents. HTML is simple enough to allow a source code management system to merge changes made by different people. Although Word can track and merge changes, it does not lend itself to this level of collaborative development.

HTML's hyperlinks make it easy to divide documentation into manageable chunks, and then link between the different parts. This allows you to write documentation that is broken down to mirror the structure of the IT solution, and still read it coherently.

HTML works well with other technologies. It is easy to link to other pages or files. Although HTML itself does not include drawing commands, adding diagrams is easy. I create diagrams using Inkscape, and then export them as portable network graphic (PNG) files to include as pictures in the documentation. Although this takes a little longer than the drawing tools in Microsoft Office, the drawings are much easier to maintain and reuse through the life of the documentation.

Lastly, I like HTML just because it is simple. Although it is possible to produce nearly any formatting effect in both Word and in HTML, HTML's simplicity makes it a lot less tempting. You focus more on producing simple, readable, usable documentation, rather than unnecessary formatting.

I do not use HTML for everything – I would not use it for writing a proposal or management report. But it is much better than Word for the bulk of documentation we create in IT.

Next: Programming is the last thing you should do

Subscription

Subscribe to RSS feed

Latest newsletter:
Magical metadata

We use the term "metadata-driven" to describe IT solutions in which functionality is defined in data. Taking this to the extreme can provide unparalleled levels of speed, simplicity and versatility.
Read full newsletter

System governance

System governance helps you implement high-quality systems, manage existing systems proactively, and improve failing systems.

Find out more