TweetFollow Us on Twitter

Writing A ReadMe File

Volume Number: 14 (1998)
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 people about it up front. And, if your software is freeware, mention that as well. I prefer that pricing information be given in a clear, business-like fashion, without long-winded discussions about ethics. Be sure to tell people exactly what to pay and how. (As an aside, for shareware consider using a credit card handling service for payments; typically such services make it significantly simpler to pay and thus increase the number of registrations. They also decrease the amount of time you spend bookkeeping.)

If you sell the software in shrink-wrap, you can probably skip the price (though if the ReadMe file in question goes with a free update, do clarify that the update is free). I strongly recommend providing a pointer to pricing and sales information, by phone and Internet. You never know when someone will want to order more copies or when a pirate will want to come clean. Further, you'll make software reviewers happy, since they often write about software at weird hours when phones are not staffed.

Once you jump the hurdles of name and price, your next concern is an "elevator statement," a short, compelling description that can be rattled off in the time it takes an elevator to climb from the ground floor to the penthouse (that's all the time you may have to sell your software to the busy person who works in the penthouse suite). Writing a short description is easy: "it changes the desktop pattern," or "it's a database of amusement park rides." The compelling part is harder because it identifies what makes your software special. A full elevator statement might be, "it monitors a user's actions to figure out her mood, and then changes the desktop pattern to match," or "it's a database of amusement park rides with ride ratings from Macintosh programmers."

Why Bother?

The elevator statement acts as a hook that catches interested users, but to reel them in, you must give more details. You don't have to write an essay - all you need is a paragraph or so that backs up the elevator statement with more information. Why did you bother to code the software? Why should potential users bother to install and launch it? What unique features does it bring to the table? In particular, be sure to mention the unique features, especially if your product resembles others in its category. For example, Jerry Åman from Optima System wrote in the MailSpinner 1.2 ReadMe file, "This folder contains a kit with an AppleScript and templates that show how all mail in an Eudora or Emailer mailbox can published on the Web using PageSpinner. This kit can be useful if you run a small mailing list and you need to publish mails on the Web or you want to maintain a simple guest book at your site."

If your software only serves one simple function, you don't need much more than a slightly elaborated elevator statement; however, if your software has a number of capabilities, list them, perhaps in a bulleted list. That way, users can quickly get a broad picture of the features.

Also, when releasing an update, give the scoop on what's new in it. Some ReadMe files even include complete version histories, which is fine, though I recommend relegating version histories to the bottom of a ReadMe file or even to another document since they serve more as reference material than as newsworthy information.

Help Users Jump the Learning Curve

Pushing users up the learning curve goes a long way toward creating happy users. Every product should ship with fundamental information like system requirements, major conflicts, and what files get placed where by your installer. Often, the ReadMe file is a good place for that information.

At times, the ReadMe file is the perfect location for installation directions. If files need to be located specifically inside certain folders, say so. If the software only works in tandem with a particular system component, mention it.

In some cases, it makes sense to put basic documentation in the ReadMe file. In particular, give readers the benefit of your experience with the software - tell them about special keyboard shortcuts, unique preferences, and smart techniques for working efficiently.

Outlining the Facts

Writing the basic facts is a good start for a ReadMe file, but the text will be more user-friendly if you arrange the facts in logical order. Of course, there are many different ways to accomplish this, but here's a sample outline that should be a handy starting point for most ReadMe files. In the sample, in some cases, the headings correspond to topics that could be quite long, such as documentation and version history. For many ReadMe files it won't make sense to include these long sections; however, in any ReadMe file you can refer readers to other documents, such as a separate version history file or the printed manual.

Product name and version number
Company name
Elevator statement
New and special in this release
Hardware and software requirements
Installation instructions, getting started tips, and documentation
Important known problems
Version history
Pricing information
Contact information
Date or copyright date, and other legal information

Be a Pro

In addition to creating a ReadMe file's content, it's important to make the content look good and read smoothly.

The Argument for SimpleText

When it comes to ReadMe files, content is king, and it takes precedence over looks and glamour. To ensure readability, I suggest using SimpleText as a file format. SimpleText may be dull, but it's also universal. In addition, SimpleText has an easy user interface - users navigate simply by using the scroll bar or the keyboard, without having to master a special user interface. Also, anything but text makes people like download-site administrators crazy because these people often must extract the text for use on their systems.

HTML in particular seems a likely possibility as a SimpleText alternative, and until yesterday, I hadn't decided whether to recommend HTML as an alternative format for ReadMe files - most people have Web browsers, and I find the capability to link a ReadMe file to pages on the Web fairly compelling. Yesterday, however, I downloaded the version 1.2 update to Macromedia Dreamweaver, a high-end Web authoring program. In the update's ReadMe file, I found a lesson in how not to do a ReadMe file in HTML.

My first stumbling block came when I blithely double-clicked the ReadMe file's icon before realizing that I'd have to wait for Navigator to launch (right now, I use Internet Explorer as my primary browser). The second stumbling block, however, was far more annoying. The ReadMe file itself lacked almost all information normally found in a ReadMe file and instead linked to Macromedia's Web site. To view the release notes, feature overview, FAQ, and so on, I had to go out on the Internet and wait for Web pages to load. And, to learn some details, I had to hunt around on Macromedia's Web site. The ReadMe file had been created for Macromedia's convenience, not mine. Unless Macromedia updates the ReadMe file, you can view it as I saw it at http://www.macromedia.com/support/dreamweaver/releasenotes/dw1_2_readme.html.

Despite this recent bad experience with an HTML-based ReadMe file, I think HTML-formatted ReadMe files can work well if they provide all the important core details and then use links to give fast access to related information, such as extended documentation or an online order form. Without providing substantively useful links to extended information, though, I can't see much point in doing a ReadMe file in HTML, since SimpleText works better for presenting local information.

ReadMe files come in plenty of other double-clickable formats, but they all require more brain cycles from busy readers than a SimpleText file. A software update or shareware program may only get 30 seconds of attention from users cruising software archives or reviewers checking out all the applications in a category, so to attract attention you must make opening the ReadMe file take only a fraction of those 30 seconds. For serious commercial software, you'll receive more than 30 seconds of attention, but you'll make people's lives easier if you distribute ReadMe files in a format that's easily accessible.

SimpleText Authoring

If you've never delved into hard-core SimpleText authoring and want pointers on using ResEdit to incorporate styled text or graphics into a SimpleText file, read the Apple Developer Technical Support Technote 1005, "The Compleat Guide to SimpleText," by Bryan Stearns and revised by Mark Cookson The Technote has general tips for ReadMe authors and lots of detailed information about adding graphics and movies to SimpleText document. http://developer.apple.com/technotes/tn/tn1005.html.

Many of my programmer friends, however, do not recommend SimpleText as an authoring environment; instead, they use a word processor like ClarisWorks with an XTND translator that converts the file into SimpleText format.

Users like unlocked ReadMe files because it's easy to grab URLs and email addresses from them. As a software reviewer, I love them because I would far rather copy contact information than retype it - copying is faster and reduces errors. Although I acknowledge that people can easily alter an unlocked SimpleText document without your permission, an unlocked ReadMe file will also make you many friends.

Unfortunately, as the Technote 1005 confirms, unlocked SimpleText documents experience buggy behavior if they include graphics. I'd much rather be able to copy text from a ReadMe file and have URLs potentially be live (through ICeTee, for instance) than be able to see a screen shot.

The Naming Game

Naming a ReadMe file is much easier than naming a pet. Simply make the name descriptive and include the name of the product. I recommend putting the product name first so the ReadMe file can sort by product name within a Finder window. Examples of good names include: ScreenCruiser: Read Me First!, RideRater-ReadMe, and Mood Scanner Users Read Me. Avoid non-descriptive names like ReadMe and ReadMe First! Additionally, unless you are in grade school, skip overly enthusiastic names like README!!!!!!

Letting It All Lay Out

Layout and fonts also play a role in creating a ReadMe file. The point of a ReadMe file is to present textual information, so it's terrifically important to use fonts that read nicely onscreen. I recommend tried-and-true screen fonts like Geneva and New York; other commonly installed fonts include Chicago, Helvetica, Monaco, and Times. Above all else, resist the temptation to use a font size that looks good when printed but tiny onscreen (never use type smaller than 12-point). If you ship a ReadMe file in read-only format, it's particularly discourteous to use a small font size. Similarly, italic text is hard to read onscreen and is best avoided.

Beyond font choice, SimpleText doesn't offer much in the way of layout options, but when in doubt, I suggest following the advice of Macintosh layout expert Robin Williams. In the excellent The Non-Designer's Design Book, (Peachpit Press, 1-56609-159-4), Robin points out four principles of design: proximity, alignment, repetition, and contrast. In essence, information should be positioned near like information (i.e. put all contact information in the same place); chunks of information shouldn't be splatted down randomly, but instead should be placed next to one another in a logical manner; items like big headlines should repeat in a consistent manner with regard to their styles and the white space surrounding them; and you can add visual excitement by using layout elements that contrast (in a ReadMe file this might amount to using contrasting text styles for heading and body text).

Seven Steps to Writing Success

The most important aspect of a ReadMe file is the text it contains, and the quality of the writing counts. Because casual writers often compose ReadMe files, I submit to you seven quick tricks for taking any piece of ReadMe file writing and making it read more like it was written by a professional:

  1. When referring to a command or dialog box, spell it exactly as it appears in the program. (Optional points - contemplate why software reviewers love dialog boxes that stick around when the reviewers switch out of the software to a word processor.)
  2. When referring to a menu command, don't use quotation marks and mention the menu in case readers don't know which one to use.
    • Do: Choose Arrange All from the Window menu
    • Don't: Use the 'arrange' command on the 'window' menu.
    • Do: From the Special menu's hierarchical Find menu, choose Search.
    • Don't: Pop up the "Find" menu and click the command for searching again.
  3. Remove these words and phrases: "actually," "a lot," "very," "really," and "just." By and large, your writing will be far stronger if you take them out.
  4. This step is hard, so skip it if you don't have time. Look for instances of the passive voice (sentences containing words like "is," and "are") and try to rewrite at least half the sentence so the "is" or "are" disappears. Generally, avoiding the passive voice makes your writing more precise, more understandable, and more powerful.
  5. Use a spell checker.
  6. Read the ReadMe file out loud. If you make changes based on what you hear, run the spell checker again.
  7. If the ReadMe is written in a language that is not your primary language, consider having a native speaker tweak it. If that's not possible, make it clear through your contact information or a short note that you did your best. Most people will forgive errors once they understand the cause.

If you truly can't justify the time it takes to polish the writing in a ReadMe file, I recommend acknowledging bluntly that you didn't think it was worth the effort. For example, the IMPORTANT README that comes with IADD 0.0.2 modeled itself after a FAQ (a format that, in fact, works rather well). Here's an excerpt:

Did you do a lot of testing on this? No, This took about 3 hours to make and has been tested for about 15 minutes. It seems to work.

How much memory does it use? I'm not sure, but I would guess around 5K.

How much does this cost? $0.00 (It is free.)

Didn't you proofread this document? No, I didn't. I made it in SimpleText and did not proofread it. If you find a mistake that really bothers you, let me know.

ReadMe Checklist

Creating a great ReadMe file requires far more perspiration than talent. Here's a checklist to sweat over as you finish a ReadMe file; if the document meets the requirements on this list, it's probably ready to ship.

  • The ReadMe file makes it a complete no-brainer to figure out your company's name (or the programmer's name), the application's name, and the version number.
  • The ReadMe file includes the release date of the software.
  • The ReadMe file contains reasonably complete contact information.
  • Readers of the file can easily determine pricing information (for some commercial software, this criteria isn't necessary, but for shareware it's terrifically important).
  • The first screen of the document has a description of what the software is and why it's cool.
  • The ReadMe file mentions new features in this particular release of the program.
  • The ReadMe file notes system and hardware requirements for the software.
  • The ReadMe file contains installation instructions, tips and tricks, documentation, and a version history (or if it doesn't, it refers readers to other documents that do contain this information).
  • The application's name is spelled consistently throughout the ReadMe file (make sure you have also spelled the company name consistently).
  • The file format is SimpleText (or, if not, you have a good reason for using something else).
  • If feasible, the document is unlocked so that readers can freely copy information and access URLs.
  • The file's name is descriptive (ReadMe alone is not sufficiently descriptive).
  • The font styles and overall layout are appropriate for onscreen reading.
  • You have followed the seven steps to writing success outlined in this article.

ReadMe Last

Writing a good ReadMe file shouldn't be a back breaking task, and I hope this article has given you ideas for improving your next ReadMe, or even given you tools in the form of the suggested outline, seven steps to writing success, and shipping checklist. If you remember nothing else from this article, I hope you'll remember that for a ReadMe file, content truly is king - provide good information in a useful format and you'll not only make friends, you'll also gain paying customers and be more likely to receive favorable press coverage.

Bibliography and References

  • Williams, Robin The Non-Designers Design Book, Peachpit Press. Berkeley, 1994.

A freelance writer and Macintosh enthusiast, Tonya Engst is best known for her work on TidBITS, an electronic newsletter centering on the Macintosh Internet community. She has been reviewing Macintosh software since 1990, often under tight deadlines, and has strong opinions about what constitutes a useful ReadMe file. Tonya holds a degree in communications from Cornell University. Her home page is at: http://www.tidbits.com/tonya/.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

OmniOutliner Pro 5.8.5 - Pro version of...
OmniOutliner Pro is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It's... Read more
OmniOutliner Essentials 5.8.5 - Organize...
OmniOutliner Essentials (was OmniOutliner) is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually... Read more
Quicken 6.3.0 - Complete personal financ...
Quicken makes managing your money easier than ever. Whether paying bills, upgrading from Windows, enjoying more reliable downloads, or getting expert product help, Quicken's new and improved features... Read more
Viber 15.8.0 - Send messages and make fr...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Butler 4.4.2 - Hot key, menu, and keywor...
Butler makes it easier for you to perform a wide variety of potentially recurring tasks. Just arrange these tasks in Butler's fully customizable configuration and assign one or more triggers to a... Read more
GIMP 2.10.24 - Powerful, free image edit...
GIMP is a multi-platform photo manipulation tool. GIMP is an acronym for GNU Image Manipulation Program. The GIMP is suitable for a variety of image manipulation tasks, including photo retouching,... Read more
ScreenFlow 10.0.3 - Create screen record...
ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your entire monitor while also capturing your video camera, microphone and your... Read more
Notability 10.4.5 - Note-taking and anno...
Notability is a powerful note-taker to annotate documents, sketch ideas, record lectures, take notes and more. It combines, typing, handwriting, audio recording, and photos so you can create notes... Read more
Day One 6.7 - Maintain a daily journal.
Day One is an easy, great-looking way to use a journal / diary / text-logging application. Day One is well designed and extremely focused to encourage you to write more through quick Menu Bar entry,... Read more
Vallum 4.0.3 - $15.00
Vallum is a little tool that helps you monitor and block apps connections and throttle apps bandwidth. It is able to intercept connections at the application layer, and hold them while you decide... Read more

Latest Forum Discussions

See All

The 5 Best Mobile Stealth Action Games
Action games are a hard sell on mobile, and they get even harder if the more precision they require. Stealth games are one such subgenre that just doesn’t feel like it could work well on small touchscreens where you’re prone to being distracted or... | Read more »
Exos Heroes' latest update introduc...
LINE Games has announced that several pieces of content in their popular RPG, Exos Heroes, have received changes to celebrate the summer season. There is also a new story event to tackle called Memorial Saga that follows Ramge, the Prince of North... | Read more »
Infinity Island is a cutesy idle game fr...
Infinity Island is a brand new idle game from Luca Redwood that is available now for iOS and Android. You might be familiar with Redwood from their previous games, 10000000, You Must Build A Boat and Photographs. [Read more] | Read more »
Infinite Galaxy is a deep sci-fi strateg...
The collapse of the Empire is nigh. In its wake, remnants of the epic intergalactic struggle float through the debris in space, as lawless pirates sow seeds of discord and loyalist groups strike terror into the hearts of innocent civilians. In the... | Read more »
Injustice 2 Mobile's latest update...
Warner Bros Games and NetherRealm Studios have released a major update for their fighting game, Injustice Mobile 2. It sees the arrival of a brand new character, Vixen, to the game alongside changes to the existing progression system. [Read more] | Read more »
Pokemon Go's August events have bee...
Following Pokemon Go Fest 2021, it's time to look ahead to August and the events that will take place in Niantic's AR game throughout the month. There's a new Research Breakthrough encounter, 1 PokeCoin bundles and a bunch more. [Read more] | Read more »
Overboard!, Inkle's reverse whodunn...
Inkle's fresh approach on the whodunnit mystery genre, Overboard! is now available for Android devices followings its release on iOS. The game has received predominately positive reviews since it launched. It holds a healthy Metacritic score... | Read more »
There's never been a better time to...
We were obviously big fans of Genshin Impact when it launched last year, so much so that it grabbed our Game of the Year award. Since that time, though, the game (and our enthusiasm fo it) had gone somewhat quiet. [Read more] | Read more »
Homeworld Mobile's first regional b...
Since the initial announcement all the way back in 2019, we've not heard an awful lot about Homeworld Mobile. But now, there appears to be some movement as the game's first regional beta test is now live. [Read more] | Read more »
Masketeers: Idle Has Fallen's impen...
Appxplore has announced that their popular RPG Masketeers: Idle Has Fallen will soon receive a major update that introduces a Guild system alongside another feature called Sigils. The developers hope this will add more excitement to the game by... | Read more »

Price Scanner via MacPrices.net

Verizon offers $200 discount on new Apple M1...
Verizon will take up to $200 off the price of an M1-powered Cellular iPad Pro with select trade-in and monthly payment plan (24 months). The fine print: “Less $100 promo credit applied to account... Read more
Record low prices on Apple’s 13″ M1 MacBook A...
Amazon is offering a $150 discount on Apple’s 13″ M1 MacBook Airs with 7-Core GPUs and 8-Core CPU. With Amazon’s discount, their price drops to only $849 with free shipping. Their prices are the... Read more
Save up to $140 on an M1 Mac mini at Apple wi...
Apple has a full line of standard configuration M1 Mac minis available in their Certified Refurbished section starting at only $589 and up to $140 off MSRP. Each mini comes with Apple’s one-year... Read more
Here are the details of Apple’s sales tax hol...
Apple is participating in the 2021 sales tax holiday again this year. In certain states on certain days customers are eligible to save on the sales tax for items purchased on Apple’s online store.... Read more
Apple has 13″ M1 MacBook Pros available for $...
Apple has a full line of 2020 13″ M1 MacBook Pros available Certified Refurbished, starting at only $1099 and up to $230 off original MSRP. These are the cheapest M1 MacBook Pros for sale today at... Read more
Our exclusive Apple Price Trackers help you f...
Our Apple award-winning price trackers are the best place to look for the lowest prices and latest sales on all the latest Apple gear. Scan our price trackers for the latest information on sales,... Read more
The best deal on 13″ M1 MacBook Airs are thes...
Apple has a full line of 2020 13″ M1 MacBook Airs available, Certified Refurbished, starting at only $849 and up to $190 off original MSRP. These are the cheapest M1 MacBook Airs for sale today at... Read more
Reminder: Take advantage of Apple’s Back to S...
Take advantage of Apple’s Back to School promotion for 2021. As part of this promotion, Apple will include one free pair AirPods (with charging case) with the purchase of a MacBook Air, MacBook Pro,... Read more
Sunday Sale: Amazon is offering record-low pr...
Amazon has Apple’s entire MacBook lineup on sale today for record low prices, with models available starting at $899 and up to $500 off Apple’s MSRP. Shipping is free. These are the same MacBook Pros... Read more
Sunday Sale: Apple Pencil 2 for only $99, sav...
Amazon has the Apple Pencil 2 on sale today for only $99 shipped. Their price is $30 off Apple’s MSRP, and it’s the lowest price available for an Apple Pencil 2 anywhere. For the latest prices and... Read more

Jobs Board

*Apple* Support Specialist - Robert Half Tec...
…organization in Lawrenceville, New Jersey is in need of a highly experienced Apple Support Specialist! The Apple Support Specialist will be responsible for Read more
Geek Squad *Apple* Consultation Professiona...
**818649BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store Number or Department:** 001045-Mountain View-Store Read more
Head of *Apple* Product Development - DISH...
…the potential to power a connected world. What you'll be doing As the Apple Product Development lead, you will make strong contributions to the product and feature Read more
Medical Assistant (CMA, RMA, LPN) - *Apple*...
…Health Fairview has an immediate opening for a Medical Assistant/LPN at the M Health Fairview Apple Valley Clinic located in Apple Valley, MN. This is a 1.0 FTE Read more
Geek Squad *Apple* Consultation Professiona...
**818139BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store Number or Department:** 000535-Portsmouth-Store Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.