Things your ReadMe must include
Tuesday, May 20th, 2008- 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.
