- Fetch Softworks
- Web Crossing
- Mark/Space, Inc.
- Microsoft
- VMware
- Bare Bones Software
- Readers Like You!
Most Popular Articles
- How to Protect Yourself from the New Mac OS X Trojans (25 Jun 2008)
- iPhone 3G GPS Details, Power Adapter, and Industrial Design (10 Jun 2008)
- Firefox 3 Bounds Forward (22 Jun 2008)
- iPhone 3G Actually $160 More Expensive (11 Jun 2008)
Recent TidBITS Talk Discussions
- 802.11g-n mixed network question (2 messages)
- New Mac threats? (5 messages)
- The Hole in My Backup Plan (19 messages)
- Firefox feature sought (19 messages)
Shopping for a new digital camera? In "Take Control of Buying a Digital Camera," pro photographer Larry Chen helps you pick out the right camera and accessories for your needs and budget. This book is loaded with tips on using your camera, pointers to the best review sites, and more!
Other articles in the series ReadMe Rules
- To Read or not to Read (27 May 96)
- ReadMe Files? Read This! (29 May 95)
Published in TidBITS 280. Subscribe today to receive TidBITS in email every Monday.
- Administrivia
- The Lotus-Eaters
- Free USR Sportster ROM Upgrade
- RAM Doubler 1.5.2 Patch
- Lower Royalties for VR
- Look, It's Windows - Can We Calm Down?
- AOL Buys Everyone
- A Studio in Silicon Valley
| 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 <morris@magic.mb.ca> 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 <gspnx@di.unito.it> 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.
ftp://mirrors.aol.com//pub/info-mac/text/tex- 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, <schmange@wbb.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.
Microsoft's MacBU: Supporting Mac users with Office 2008.Straighten up your Office with the latest updates to Word,
Excel, PowerPoint, and Entourage. Update today at Mactopia!
<http://www.microsoft.com/mac/downloads.mspx>