Section 8.7. Bad Ideas for Documentation

8.7. Bad Ideas for Documentation

The Bad Ideas in this section are mainly related to pitfalls with using documentation tools.

8.7.1. Releasing the Documentation Separately

One situation that arises quite frequently is that the release of a product is running late, and the documentation for the release is running even later. The thought occurs to someone: "Perhaps we could release the documentation separately?" Yes, you can indeed release documentation on a different schedule from the product. Just as you could make a separate release of some binary library files used by a product. However, keeping track of all the different versions involved will make your release managers' work harder, and your customers' lives probably no better. Making sure that each version of the product will always refer to the correct documentation is not impossible, but it is fraught with potential errors. The long-term effect of releasing the documentation separately always seems to be increased confusion.

A variant on that not-so-cunning plan is to ship an early (i.e., unfinished) version of the documentation with the product, and then later on provide an updated version of the documentation on a public web site. The idea is that the customer can then check for updates. Sometimes you see a Help menu with View Documentation and View Latest Documentation. This idea is not a good one either, for a number of reasons. The customer may or may not be connected to the Internet when she wants to view the documentation. The customer may not be allowed to update the installed documentation. The busy system administrator who installed the product will not have time to check for updates and will likely disable automatic notification about available updates. Again, just say no, and release the correct documentation as an integral part of the product.

8.7.2. Ransom-Note Cut and Paste

The way that different fonts in a document are displayed can vary widely from one editor and platform to another. So long as all the glyphs (graphic symbols) for all the different characters are present, this doesn't usually affect how the document is read. But sometimes two fonts that are almost identical in appearance on one machine can appear quite different from each other on another machine, or when transformed into another file format. What happens then is that when changes are made in the document on one machine and the wrong font is used, maybe because "it looked close enough," the changes stand out on the other machine like the cut-out letters in a Hollywood-style ransom note.

For example, the original announcement document may have looked like this:

Here at Tasteful Pets we look forward to a deep and meaningful relationship with Rabbits, Inc. and believe that their product FurWare is best of breed.

All the text is in one font. Then you decide to use this particular document as a template for your next announcement. You copy the name and product of your new partner, Foxes, Inc., from some other document and paste it into the announcement. To your surprise, you see:

Here at Tasteful Pets we look forward to a deep and meaningful relationship with Foxes, Inc. and believe that their product FoxyLadies is best of breed.

In this case it's pretty obvious that a different font was used wherever the new name was cut and pasted from. But what if the fonts differed only by a single point size, or even worse, in some way that your text editor doesn't even show you? Then the difference may not be at all obvious until the document is viewed with a different editor or is converted to another file format such as HTML.

This can be especially embarrassing in press releases where company executives' names are changed. The obvious solution to this is to make sure that when you cut and paste text, the fonts match in name, not just by eye, and to preview the document on several different systems and file formats. Another slow-but-sure fix is to select each paragraph in turn and reset the font or formatting for the whole block. Remember: cut and paste is cool, but only if no one can tell you did it.

8.7.3. Old Versions That Never Die

Some tools such as Microsoft Word can save previous versions of a document as it is changed. This is useful for generating change bars and similar editing marks. It's also a lot faster to append recent changes internally when editing a document, rather than modifying the file in many places. However, if you forget to remove the previous versions before you publish the document, the different versions are all there for people to see.

This may be as harmless as people seeing your common spelling mistakes, or it may show changes in financial information that were never supposed to be disclosed. This is of particular concern if the document has been redacted (lines of text blacked out for reasons of security) and then the previous version of the document contains all the sensitive information anyway. This has happened a number of times in recent years, just because no one realized that the earlier versions were still present in the file format when it was released.

8.7.4. Funky Filenames

Different filesystems have different quirks about how their files and directories are named. Using the directory separator (/ on Unix, \ on Windows) in filenames is always a bad idea. Unix shells also use some other characters, such as ; * ? > < $ % | , so avoid these too. Macintosh filenames should not have colons in them. These rules are easy to follow by using only alphanumeric characters for filenames. There is also the problem of case: File_A and file_a refer to the same file in Windows, but they refer to two distinct files in Unix.

One common problem is that both Windows and Macintosh filesystems support spaces in filenames, whereas Unix filesystems do so only grudgingly. Some Unix tools such as shells and their commands will handle filenames with spaces by quoting the filename or preceding each space with a backslash (\ ); it varies by shell. Other common command-line tools such as find and xargs will take extra arguments to change how they use filenames, if you remember to add them. Older versions of CVS and related SCM tools didn't handle spaces very well either.

If you are expecting to use files across multiple platforms, keep these issues in mind when creating filenames. Renaming files later on is a tedious problem when the filenames have been used as part of links or images in a document.

8.7.5. Screenshots

Screenshots can be the bane of producing documentation on a tight schedule. They are tricky to capture, tend to change dramatically as the product develops, may need editing to remove sensitive information or spelling mistakes, and are often unreadable by the time a document is printed. A good screenshot at just the right point in a document can indeed be worth a thousand words, but you can describe many ideas better with just a few hundred well-chosen words. Far more helpful than an outdated screenshot with hard-to-read text and fuzzy images is a clear set of conventions throughout a document for describing the various prompts, the text that is entered, and any menu choices. If you have a long list of steps to follow, provide ways to check that the steps are working correctly as you go, rather than a screenshot of every other step.

If you must use screenshots (for example, in online help or tutorials), make sure that their file format and the resolution at which they are acquired is appropriate for all the release formats. It's very frustrating to click on a thumbnail image on a web site only to receive an image that is larger but still too small for you to see anything useful! You may also want to print the documentation regularly to make sure that the screenshots are still useful in black and white. Using links to screenshots rather than embedding them directly within the source document can help reduce the size of the files, but at the cost of more link checking as part of the production process.