Writing A ReadMe File
Volume Number: 14
Issue Number: 10
Column Tag: Electronic Documentation
Writing a ReadMe File? Read This
by Tonya Engst
A member of the Macintosh press tells all. Learn about the
link between a ReadMe file and press coverage, plus
discover the secrets of a great ReadMe file
ReadMe First!
Nobody expects to find great literature in a ReadMe file, and that's good news for busy
developers writing ReadMe files for their software. There's no need to consider the
symbolism behind RAM requirements or make metaphors out of multiple minor
updates. Even so, taking the time to construct an informative, user-friendly ReadMe
file will create satisfied, paying customers; win you friends; and even help turn the
limelight of press coverage in your direction.
Although plenty of products have wonderful ReadMe files, over the years, I've
encountered a disturbing number of ReadMe files that practically cripple their
products through inattention to detail or random organization. Sometimes a bad ReadMe
file causes my attention to wander so I never get around to trying its associated
software; other times, I'm writing about software for publication and the more time I
spend chasing down basic information about the software (for instance, how much it
costs), the less time I have to appreciate the good qualities of the program and expound
on them in print.
In this article, I'll look at what information to put into a ReadMe file, offer a sample
ReadMe file outline, talk about file types, and give tips for polishing writing quickly.
The article ends with a checklist: if a ReadMe file meets the criteria in the checklist,
it's ready to ship.
Just The Facts Ma'am
Whether a product is distributed electronically or in shrink-wrap, a good ReadMe file
concentrates on basic, vital facts: Where does this come from? When was it made?
What is it? Why should I use it? How do I use it?
Daddy, Where Does Software Come From?
This part is easy. In the ReadMe file, type your complete contact information, or at
least all the information that you want to share. Consider reasons why people might
want to reach you: feature suggestions, bug reports, questions, payments, and even
flattering comments. Users will look for contact information in order to send payments
or ask questions (often users will have a question or two that needs answering before
they're willing to pay for shareware), and journalists reporting on your software will
look to the for contact information to include in their articles. I've actually had to
scratch covering products because I could not locate contact information before a
deadline. Here's an example of how to do it right:
Contact us at:
Joe-Bob's Software Mill
http://joe.bob-soft.com/
joe@bob-soft.com (sales, distribution requests, administration)
support@bob-soft.com (bugs, problems, questions)
800/555-1212 (M-F, 9 AM-4 PM PST)
When?
This key piece of data is so small that it's easy to overlook. Nevertheless, be sure to
date the ReadMe file. It's a polite way to help people place the era in which your
software shipped. For instance, if I see a ReadMe file dated from 1992, I'll be much
more forgiving of a lack of Web URL or current contact information. I'll be more
cautious about installing it on an up-to-date system, and I'll cruise the net to check
for a later version.
What is It?
A good ReadMe files tells what the software is named, what its version number is
(rank and serial number are optional), what it costs, and what it does. Provide these
details and you make many people happy - users can figure out what to expect from the
software, those who run download sites can categorize it rapidly, and members of the
press can wrap their minds around it does quickly.
You'd think that writing the name and version number of software would be simple,
but some ReadMe authors slip up and don't consistently give the same name throughout
the file. Though most users won't care, it looks unprofessional and makes journalists
grumpy because they then must figure out which spelling you meant. In particular,
watch out for spacing and capitalization - screenCruiser isn't the same as Screen
Cruiser. (While you're at it, make sure the name is also the same in the software's Get
Info box and Finder icon name.)
If you sell the software as shareware, postcardware, donationware, or the like, tell