This article originally appeared in TidBITS on 1995-06-05 at 12:00 p.m.
The permanent URL for this article is:
Include images: Off

ReadMe Files? Read This Follow-up!

by Tonya Engst

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 <> 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 <> 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. edit-plus-132.hqx

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, <> 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: