A Collection of Documentation Glitches

Neglecting the process of document creation may have surprising consequences.

Consider the following four cases;

  1. A major automobile manufacturer produces an impressive cd-rom that presents their centre for design and prototyping. This centre is already a showcase for this manufacturer. The cd-rom is designed to highlight this activity even more.

    However, in one of the English language sequences, the presenter, who has been excellent throughout the rest of this multimedia presentation, makes a slip and lets out a noisy exclamation: shit!

  2. A well-known software publisher provides their customers with an administration guide for an Internet server. However, this documentation contains an example of code that would open up a major breach in security if it were implemented.

  3. Another publisher - of financial software, this time - produces a system administrator's guide containing a text where the variable <VAR> is explained under the heading the variable <VAR>=, a mathematical impossibility, and one that is embarassing given that system administrators are generally required to have some ability in mathematics.

  4. A publisher of cad/cam software provides a glossary with their modeler's documentation. As a definition of trihedral the document should have given the one used in cad/cam, in other words, a symbolic representation of the axes corresponding to the three dimensions. Instead, the definition used concerns pure and not applied mathematics: a figure comprising three surfaces and not the angle formed by the intersection of these surfaces. If the users of the modeler didn't know what a trihedral is, the text - poorly adapted to their case - would not have allowed them to get a clear picture of the meaning of the term.

What all four cases have in common

What do these cases have in common? In each, an error has slipped in through a lack of attention in the documentation production cycle, and has remained unoticed. The result: the image of the manufacturer is damaged. What reader will remember the beautifully presented information on the automobile manufactuer's cd-rom? It's the four letter word that he will remember above all. What an association for a product to have!

No system administrateur will be able to take seriously the promises of the software server publisher if he notices an error in an example of code, whether it's before of during the installation and configuration of the product. What's more, in the second case, he will expose his system to risks of intrusion.

Conclusion

Watch out! Documentation is not an end in itself. It is an important part of the user's experience of your product as well as an extension of your technical marketing. On condition that it is truly user-oriented.

To find out how Open Globe can avoid glitches damaging to your image, contact us using the form on the Contact page