Hide full article
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.
<http://www.kagi.com/>
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.
