The Readme File

Unlike most other documentation, the readme file is one document that is most likely to be the programmer's responsibility. In the bad old days of MS-DOS software, readme files were an essential part of a program. You actually had to explain how to install a program, what the name of the setup program was (it wasn't always Setup.exe), how to type it in, and what to do if the installation didn't work, which it often didn't. The readme file was an essential starting point in the installation process.

Today, you don't even have to look at the installation disk or CD-ROM. Just pop it in the drive, run Setup.exe, perhaps restart Windows if a file was already in use, and you're ready to go. CD-ROM-based programs with an AutoPlay program that launches the setup program when necessary are especially good. Today, the setup program does almost everything for the user. No more modifying the Config.sys and Autoexec.bat files. No more setting environment variables. No more loose ends that need to be tied up.

Does this mean that the readme file is obsolete? I don't think so. The readme file is best regarded as your last defense against technical support calls. You should always provide an informative readme file that gives users tips on how to solve technical support-related problems. Although there are no guarantees, many desperate users give the readme file a chance before picking up the phone.

TIP

---

The readme file is your last defense against technical support calls.

But where does this information come from? As a programmer, you should be able to anticipate many problems based on your knowledge of the program. My favorite source of readme file information is the QA process itself. Keep track of the various issues that arise during the QA process and look for themes. If testers are having problems, most likely your users will, too. Any issues that are not adequately addressed in the program, the installation, or the documentation are prime candidates for readme file material. Since the installation process is so important, it is also a good idea to repeat important setup information even if it is adequately addressed elsewhere. Your QA team should be able to help you gather this information.

Lastly, like anything else, your readme file should be usable. A huge random collection of mostly useless information is unlikely to be read and will accomplish nothing. A good rule of thumb is that if you can't stand to read it, your users won't be able to either. Try to present the most useful information in an organized manner.

Although I've suggested a number of ways in which you can help your technical writer create excellent documentation, don't interpret this to mean that tech writers aren't capable of doing their jobs. They are. Almost all of the tech writers that I've worked with have been professional, knowledgeable, and hardworking. If a tech writer disagrees with some of your objectives or ideas, have an open mind because that person is likely to be right. But, like anyone else, your technical writer is going to need help to do the best work possible.