READ ME files: Writing Excellent Ones
These articles on the "Read Me" files that should accompany every program available on the Internet are excellent, and Tonya Engst at TidBITS has graciously allow me to repost them as an FAQ on my web site. Thanks Tonya!ReadMe Files? Read This!
by Tonya Engst tonya@tidbits.com
Lately I've spent a lot of time sorting through shareware and freeware utilities for a number of projects, trying to find basic facts for each utility, such as what the utility does, who wrote it (first and last name), how I should pay if I like it, and how I can reach the author by email. Surprisingly, these facts are often omitted, tucked away in odd places, or poorly explained. So, here's some complaining and some advice for ReadMe file writers.
Make an Elevator Statement -- I once read an excellent book called "The High Tech Marketing Companion," by Dee Kiamy (Addison-Wesley. ISBN 0-201-62666-7), which suggests that every product needs an elevator statement. An elevator statement conveys what a product is and what's cool about it, in the time it takes to ride an elevator from the lobby to the top floor of an office building. The idea is that you may only have that much time to explain your product to a venture capitalist riding the elevator with you. Whether or not you're bucking for venture capital, every utility's ReadMe file should have such an elevator statement, along with the price of the software, the name of the author, and the author's contact information.
Make it Open -- ReadMe files are often set up as SimpleText read-only documents, so you cannot copy text from them. This makes it more difficult to be certain you get email addresses, names, and so on correct, should you be attempting to review the software or drop an author a note in email. In addition, if you want to copy the author's snail mail address to send in your shareware payment, such read-only documents get in the way even more. Read-only documents are used to prevent people from changing them, but I don't think this is a significant concern.
Make it Legible -- My final bone to pick concerns legibility. Many authors format ReadMe file text in a tiny size with no white space between paragraphs. Some authors assume I'm going to print out the ReadMe: a poor assumption, since until I can figure out what the application does, I'm unlikely to turn on my printer, and in general, I don't print, and nor should I, given that the documentation already exists online where I can file it neatly with the application.
If you create a ReadMe file, please consider the people who will read it. Make the characters large enough to be legible, accommodate people who want to read it online, explain what your product does and who you are, and remember that the quality of your ReadMe may influence not only how many people use your product, but also how many people figure out how to send you friendly messages, registration forms, chocolates, site license fees, and so on. If you've got a great application, be it freeware or shareware, don't saddle it with a lousy ReadMe.
This article is republished with permission from TidBITS, issue #279.
ReadMe Files? Read This Follow-up!
by Tonya Engst <tonya@tidbits.com>
TidBITS readers sent in a number of helpful or amusing comments in response to my "ReadMe Files? Read This!" article last week in 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.
This article is republished with permission from TidBITS, issue #280.
To Read or not to Read
by Tonya Engst <tonya@tidbits.com>
Almost exactly a year ago in TidBITS-279, I wrote an article about ReadMe files, those hopefully informative documents that come with most software. In that article, I pleaded with ReadMe file writers to consider their readers, and not to neglect certain information that users (and reviewers) might be seeking. Having recently completed several tasks that involved not much sleep and quite a bit of looking at ReadMe files, I'd like to revisit the topic, with some updated suggestions for ReadMe files authors. Some of these suggestions apply specifically to non-commercial programs, but many of them also apply to the new breed of public beta software.
Provide Administrative Details -- If I go to the trouble of opening a ReadMe file, I hope to be rewarded by learning the Who, What, Where, When, and Why of a program, and it would be most helpful if that information appeared right at the beginning of the file.
Who? There's nothing wrong with having a few benign mysterious strangers in one's life, but I don't extend that concept to software. For any non-commercial product, I prefer to know a first name, last name, and email address. If I send an author email, I want to address her properly; if I send an author a check, I want to fill it out fully; and if (with my reporter hat on) I write about software for publication, I must include this information or face my editor's ire.
What? Be sure to explain what your program does. Consider including a bulleted list that points out five or ten major features. If your program is a one-trick pony, write about the trick. Don't miss mentioning what types of Macintosh systems the program should work with.
Where? It's usually to everyone's advantage to have people use the latest version (and a clean version) of a program, so let your users know where they can download a fresh copy. If your program has a Web page, point users to it. Don't make users poke around in a search engine in order to find your Web page.
When? Be sure to mention the date that you released the program version. Of course, this information is approximately available in the Get Info dialog, but if your ReadMe file is a few years old, that may tip users off they should check for a more recent version.
Why? Chances are, there are ten other programs available that kind of do what your program does. Chances are also good that you wrote your program to meet a need those other programs don't quite fill. So, please, let your users know what's special about your program.
After covering those basic administrative details, be sure to spell out whether your program is free or not, and if it's not, be it emailware, smileware, chocolateware, beerware, or shareware, let people know not only how much to pay you, but how to go about paying you, especially if they don't normally use your currency. I suspect many deserving shareware authors miss out on payments simply because users found it too complicated to pay. (This is, of course, not a good excuse for not paying, but why miss payments because people can't find the time to convert their money and bundle it up into an appropriately addressed envelope?) I believe users find it too complicated to pay in part because I know a few shareware authors using the Kagi Software system for streamlining payments, and these authors have been happy with the results.
If you submit your program to the Info-Mac and UMich archives (and I recommend that you do; send it, along with a brief write-up to: <macgifts@info-mac.org>), make your brief write-up, which will be published as an abstract, also include the Who, What, Where, When, and Why, as well as the all-important payment details. (Users can search the Info-Mac archives by pointing their Web browsers at the incredibly helpful Info-Mac HyperArchive.)
<http://hyperarchive.lcs.mit.edu/HyperArchive.html>
The Importance of the How -- Once you finish covering all the administrative details, do cover the How, and don't just point people to balloon help or Apple Guide unless you are totally confident you've written awesome online help. Most people haven't. Also, be sure to point out extra cool features of your application that might not be immediately obvious, like pressing the Shift key to reveal some amazing new function or setting up your application as a drag & drop icon. The sin of How-omission is particularly present in public betas, and perhaps even more frustrating because public betas are often released by large companies who could surely spare one employee for the few hours..
Consider HTML and Other Suggestions -- A number of authors have begun releasing ReadMe files as HTML documents, or offer an easy way to read the files over the Web. I find these quite handy, because I have personalized my browser to show fonts in styles that I like. By following a link to a Web page either about the author or about the product in question, I can entertain myself by checking out the author's personality, or I can educate myself by noting the latest information about a product. (Obviously, programmers cannot easily update all the versions of a ReadMe file that have been released out to the world, but they can keep a Web page up-to-date.)
That pretty much sums up my ReadMe file recommendations, but in digging through my email from a year ago, I found some additional, previously unpublished suggestions from TidBITS readers:
David Schwartz <david_schwartz@cc.chiron.com>, wrote in to say: "One more bone to pick about ReadMe files. Name them something more descriptive than simply 'ReadMe'! How about 'ReadMe - TidBITS', or 'ReadMe - MYOB', or 'ReadMeFirst - CCatcher'? Why must a newbie's drive have a dozen files with the same name?"
Although I'd couple this suggestion from Frank Sydnor <a270@amug.org> with a dose of tolerance for authors writing ReadMe files in languages they don't speak natively, Frank's advice is still right on target: "When I see a poorly written ReadMe I (rightly or wrongly) assume the software is plagued with errors. When I see a well written ReadMe I assume this writer has an equivalently professionally written software program."
On a related note to making helpful ReadMe files, Kevin Lepard <lepard.kevin@mayo.edu> passed on this suggestion: "Put your name, address, email, amount of shareware payment, and where it should be sent in the About box in the program itself. I can't tell you how many times I've tossed ReadMe files and then wondered where I was supposed to send payment, because the only place it was located was the ReadMe file."
And so, in final summary, the success of your ReadMe file can lead people to send you chocolates, thank you notes, money, and other goodies. It can also be all the difference for making it so time-pressed journalists and authors can write something intelligent about your software, be it for an obscure newsletter or for the front page of a major publication. And, of course, the more attention your product gets in the media, the more likely you are to receive more chocolate, money or whatever.
This article is republished with permission from TidBITS, issue #330.
Modification Date: Sunday, June 30, 1996