Written by Matthias Kahlert, mkahlert@kagi.com
http://www.GeoCities.com/SiliconValley/Pines/8031/index.htm
| SimpleText |
The easiest way to create Read Me's is to use the application SimpleText. SimpleText is installed on every MacOS computer, every user has this application, so why not using this?
SimpleText is a simple word processor, it can handle any text file, it may contain styled text (different fonts, styles and sizes) and you can also include images in your text (if you know how to use ResEdit...). Therefore SimpleText is the ideal application for Read Me's.
But SimpleText has also some disadvantages: The maximum text size is 32 KByte, which may be quickly reached in extensive shareware applications. And SimpleText also doesn't provide the possibility to search through the files. It also provides nearly no graphic control (how the the images are justified, text can't flow around pictures, etc.)
Therefore SimpleText should only be used for small files. For bigger files you should take a look at one of the other possibilities.
| PICT Files |
Instead of text files you could use PICT files for your documentation. PICT is a simple picture file format that can be displayed with SimpleText, so every user can read it.
Using PICT files you have full typographic control, you can create PICTs with nearly every graphics application (like Adobe Photoshop), or by simply creating screenshots.
But depending upon how you created the PICTs, the files are often not scalable, so it looks awefull when printed out. And the user also can't search through the files or copy text parts from it.
| Self-Reading Documents |
Another good way to create Read Me's are the so-called "Self-Reading Documents". These SRDs are small applications, that display a file. You don't have to worry about whether the user has installed the right application or not, the viewer is directly included inside the Read Me.
But the biggest disadvantage is the file size: Because the complete viewer is included inside each Read Me the file size is automatically greater than of a standard text file.
But depending on the SRD generator the Read Me can provide a great luxury: table of contents, links, annotations, chapters, search features, etc.
Some of the most common SRDs are (the ones I know... not complete at all...):
| HTML Files |
Another nice file format for Read Me's is HTML. HTML gives you sufficient typograhic control, you can include images and links, the file is searchable, etc.
But the user needs a web browser in order to view that file. Therefore you should make sure that every (possible) user of your application has a web browser installed on his Mac. And that is only the case if your application is an Internet utility...
| Portable Document Format (PDF) |
Another very good file format for your documentation can be the Portable Document Format, abbreviated PDF. PDF is the file format of Adobe Acrobat.
In order to view the PDF documents the user needs a special application, Adobe Acrobat Reader. But please note: You can't be sure that every user has the Acrobat Reader installed onto his hard disk! The Reader is a quite large file, so it may be expensive for you to ship the Reader with your application.
But the Adobe Acrobat file format has some great advantages: Using PDF for your files you get full typographical and layout control. You can use any kind of images, layouts, styles and even fonts in your documents. If you used a font that the user hasn't installed, the Acrobat Reader looks for a similar font and substitutes it in the PDF file.
And there is another advantage: PDF is a cross platform file format. The same file can be viewed and printed on nearly all operating systems: MacOS, Windows, Unix, etc.
In order to create PDF files you'll need the Adobe Acrobat Distiller or any other application that is able to write the Portable Document File Format (like Macromedia FreeHand). These applications are quite expensive, so this might only be an alternative if you already have the Distiller...
| Annotations |
Now it's up to you to choose the right Read Me generator. Or do you have any other ideas or annotations about how to create Read Me's? Please let me know. Just send an e-mail to mkahlert@kagi.com.