I. The Read Me
a. Contents
All plug-ins should come with a Read Me. This should be a relatively simple document containing important information about the plug-in, including such things as:
- A description of your plug-in and what it does
- A list of all files included in the distribution
- Installation instructions
- Known compatibilities/incompatibilities with other plug-ins
- Frequently Asked Questions, if you think there might be any
- Credits & contact info
You should always assume you're writing for someone who's never used a plug-in before. For this reason, the installation instructions are very important so we'll go over them in detail.
When PC users expand your distribution the plug-ins will be in .bin format which they must convert before they are able to use them. Your installation instructions will need to include something along the lines of the following:
“For PC users to be able to use this plug-in you will first need to drag and drop the plug-in files (<give here a list of file names - they will all have the extension .bin appended to the original names>) onto the Convert Plug-ins program supplied with Nova. Once they have all been converted to .rez format you can delete the original .bin files.”
For Mac users, if StuffIt Expander is not used to expand the distribution (which will decode .bin files transparently), they too will end up with a bunch of .bin files rather than plug-in files. You may wish to mention that if this happens they should re-extract the original archive using StuffIt Expander.
After this, the process of installation is the same for all platforms. If your plug-in is actually a Total Conversion then the process may vary depending on how you have things set up so I'll leave it to you to write the instructions, just make sure you can easily revert back to the original Nova again and explain how to do so. Otherwise, installation is a simple matter of moving the plug-ins into the user's "Nova Plug-ins" folder.
b. Format
There are only two really cross-platform formats, safely usable for Read Mes: RTF (Rich Text Format) and HTML (like web pages). RTF files are easily created by TextEdit on Mac OS X but make sure not to add attachments (images) as these will appear as separate files on OS 9 or Windows. Also, be aware that hyperlinks may not work in other programs, such as AppleWorks or WordPad, so make sure the visible text of a link is the address itself (do keep all addresses in the Read Me though, rather than using .webloc files or similar as those will only work on OS X).
For more extensive documentation, like a manual or preambles, you may wish to use HTML. PDF is also a very nice format (you can create PDFs from the Print dialog in most programs on OS X), but not all users will have the software to view PDF files. If you are going to include PDF files you must include an RTF Read Me as well to tell OS 9 and Windows users that they may need to download the free Adobe Reader (http://www.adobe.com/products/acrobat/readstep2.html).
Plain text or any other text format is forbidden. I won't go into the issues with plain text, just don't use it.