Things your ReadMe must include

2008-05-20 00:23:27 UTC

  • The name of your application
  • What it does
  • How to configure the application, if necessary (note: does not include installation)
  • Simple overview of how to use the software, once it’s configured (detailed manual should be in the Help menu)
  • How to uninstall the software, if necessary (i.e., if it isn’t an application)
  • FAQ
  • What it costs, if it’s not free
  • How to register it
  • A link to your website (in case a magazine distributes your app on its CD)
  • Contact information for support questions
  • Contact information for sales (registration/pricing/currency) questions

Things that you may want to include, but aren’t necessary

  • Screenshots
  • Troubleshooting information

Things that you shouldn’t include

  • Installation instructions: If it’s a plain app, you don’t need an installer; otherwise, make an Installer .pkg. In either case, you shouldn’t need instructions.

Formats I approve

  • RTF or RTFd
  • HTML or webarchive
  • Plain text

You may also want to provide a trampoline application to open a localized version of your ReadMe (for example, see the ReadMe on the Mac OS X DVD). Bonus points if you create a kit to make these, for the benefit of other developers.

Formats I disapprove

  • Word or OOXML format: Many people don’t have Word, and everything else handles these documents imperfectly. Use RTF instead.
  • OpenOffice format: Many (probably most) people don’t have OpenOffice. Use RTF instead.
  • PDF: Use PDF either for vector graphics (inside your app) or for documents you expect someone to print. If the user is going to have to print your ReadMe, you need an interface overhaul.

As usual, I invite suggestions, rebuttals, and amendments.

UPDATE 2008-05-24: Recommended including contact information, as suggested by ssp.

5 Responses to “Things your ReadMe must include”

  1. ssp Says:

    I’d also say an easily findable e-mail address in the read me will leave a good impression.

    Why should the user have to click through a website and try to find contact info there?

  2. Wes Says:

    Handy little post. I’ll keep it in mind next time I’m writing a README.

  3. CS Says:

    Fine guidelines, but I’d disagree about PDF. It’s very common to distribute documents in PDF these days, and every MacOS X user has a perfectly good PDF viewer in the form of Preview. A nice thing about PDF (indeed, the entire point of the format) is that users see the document exactly the way the author created it, and that may be important to some authors.

    I agree that if the user needs to print your ReadMe, you’ve got trouble. Nevertheless, an author may want his or her ReadMe to look a certain way, perhaps to match the appearance of other documentation, or so that the ReadMe can do double-duty as an easily printable promotional brochure.

  4. rentzsch Says:

    Tonya Engst wrote a series of articles a while back for TidBITS. A bit dated now, but still good reading:

  5. Jesper Says:

    CS: That’s ridiculous. A readme should be designed to be read quickly on screen during installation or usage. PDF delivers something that’s paged and more of an inconvenience to scroll through, unless you’re deft enough to enable “continuous” PDF display in Preview. Anyone can deliver a perfectly charming HTML-formatted readme, if formatting is of any particular importance here, and I argue that it shouldn’t be.

    A readme should be as stripped-down as possible, even devoid of branding beyond your company/label’s name in text (not a logo!) and your application’s icon, so that nothing distracts you from the actual text. It’s not called a lookatme, and it’s not a good place to stun your audience with a coherent graphical profile or visual eloquence. I’m not opposed to such things, quite the opposite, but they have no place in a readme.

Leave a Reply

Do not delete the second sentence.