What makes good technical documentation?

Whenever we develop technical documentation we work to achieve four essential characteristics. Every piece of technical documentation should be:

  • Accurate: It almost goes without saying, but accuracy is vital. Documents which are incomplete, vague or plain wrong will be at best, annoying, and at worst, dangerous.
  • Accessible: A good document should be well structured and well written. Well structured so readers can easily find the information they need; and well written so they can understand it as quickly as possible. That doesn’t mean the document has to be simple – some subjects are complex; but in our experience those are the ones which benefit most from good organisation and straightforward, grammatical English.
  • Appropriate: Every aspect of a document – structure, content, layout and language – should be suitable for its intended audience and function. For example, a product brochure aimed at architects and other specifiers should be structured around the CIB Master List and should focus mainly on information relevant to the design stage of a project. In contrast, a site leaflet for the same product would mainly consists of instruction sequences illustrated with 3D drawings or photographs.
  • Attractive: A technical document which is a pleasure to read? Impossible? We don’t think so. Why shouldn’t your documents be visually appealing and informative? Wouldn’t that say something about the quality of your products and services?