TidBITS readers sent in a number of helpful or amusing comments in response to my "ReadMe Files? Read This!" article last week in TidBITS-279. The most common message concerned the file names given to ReadMe files. People pointed out that the Macintosh offers 31 characters for a file name and suggested that ReadMe files use those characters to take on meaningful names.
Wayne Morris <email@example.com> pointed out that the number of files that comes with a program can add to the confusion, "many software authors include several text files with their program: a ReadMe file, revision history, user's manual, etc. Sometimes none of these files is called "ReadMe," making it difficult to find an "elevator statement" and other key information. Each file should be clearly named, and the number of text files should be kept to a minimum.
Wayne also had this to say, "Many software authors put the documentation into the program and/or use online help, and think they don't need a separate ReadMe file. Think again! I might download a program simply because of the name - perhaps I'm looking for a utility for a certain task, and the name sounds promising. But once I've got it, I want to know what the program actually does before I run it. I'm even more reluctant to throw a new extension or control panel into my System Folder if there's no ReadMe file."
A few readers focused on my complaint about read-only TeachText and SimpleText documents, which do not allow copy and paste so you cannot copy information (such as URLs or snail mail addresses) from them.
Steve Rothman pointed out, "Part of my job is creating ReadMe files for commercial software. I wanted to explain at least one valid reason for making the ReadMe files read-only. If you embed PICTs in the ReadMe, they often screw up the scrolling and screen display - unless the ReadMe is read-only. Fortunately, it's easy to convert to read only and back via ResEdit or a thousand other utilities for changing type and creator [you'd change it from ttro to TEXT]."
Fabrizio Oddone <firstname.lastname@example.org> pointed out that Tex-Edit Plus [a $5 shareware utility] by Tom Bender can open read-only SimpleText documents and let you copy information out of them.
Fabrizio also noted:
Internet awareness is now easy to implement, thanks to Internet Config 1.1. In my opinion, a given application should implement four standard menus:
- Copy my/our email address
- Copy my/our WWW home page URL
- Send me/us email
- Show my/our WWW home page
1 and 2 might always be active, and 3 and 4 might work via Internet Config. I think these should be "standard-spelled" menus, becoming, as the Internet grows more and more widespread, as pervasive as Cut/Copy/Paste. [I could see menus being overkill in some applications, but such functionality could certainly live in the About box. -Adam]
And finally, <email@example.com> whose name (perhaps intentionally!) didn't come through, contributed this advice to ReadMe authors, "I'd like to add that in my rread me experiences the one thing that sticks out is grammmmatical and speellling errors.' I was al set to send in my money to a paritcular guy bu t his spellling errorz were so bAd athAT i figured no way mAn!!! So he go tno monsye get it??? anyeway when ou do yo read mne files check th espeleling."
Summing Up -- So, in the end, if you write a ReadMe, try to follow these simple rules:
Make it easy for readers to figure out what your product is called, what it does, who you are, and how to contact you. If appropriate, explain what the product costs and how to pay for it.
Consider the pluses and minuses of a read-only TeachText or SimpleText file.
Give the ReadMe file a meaningful name. If you include other informative files (such as a revision history or directions) consider whether or not it makes the most sense for them to be part of the ReadMe file. If you keep them separate, give them appropriate names.
Make sure all of your files will be legible both onscreen and when printed. Keep in mind that screen size and font availability varies considerably from user to user.
Run a spelling check. You could run a grammar check, but it's probably faster and more effective to just read the file out loud to yourself (though I expect this advice won't necessarily work for those trying to write a ReadMe file in a foreign language). If something sounds funny, fix it. You could also ask a friend to proofread the file.