General Tips

Use a format that anyone can read - either SimpleText or standalone application (e.g. DOCMaker). HTML would just about be OK, but it's not as 'friendly' a choice. BBEdit, Word, etc. are definitely not ubiquitous, so do avoid using those formats for the final distribution. If you do use one of the latter applications to write the README with (this has certain benefits, such as being able to run an automatic spell check), then either copy and paste the finished text into a SimpleText file and save that, or save as a plain text file, which has the file type 'TEXT' and so can be opened by SimpleText in the absence of the original application (or use ResEdit to change the creator code to 'ttxt' so that the file will automatically open in SimpleText).

Keep the file physically compact. Remember, folks want to play your map/scenario; they didn't download it just so they could ogle the README all day. [So avoid any embedded multi-megabyte 'Think Different' QuickTime movies and other nonsense (you know who you are...); nobody's interested.]

You should stick to standard Mac fonts, if possible (this means Times, Helvetica, Geneva, Courier, etc. - i.e. the ones that are installed as part of the System software). Remember that folks reading your notes probably won't share that obscure shareware font which you thought looked so good at the time, and all that will happen is that they'll see a standard font substituted instead (which won't look so good, and might affect positioning of text and in line images). If you do use a non-standard font, you have two options:

1. If it's a small amount of text (e.g. a banner) then consider an in line graphic instead (remembering to index the graphic as efficiently as possible [see PICT Notes] to keep to the file size down ); or
   
2. Embed the font used following the same method as described in the HUD Modification section (bearing in mind any copyright issues, and the implications for file size).

Also, as regards fonts, pick ones that will be readable on-screen. Many fonts are designed to look best when printed, and don't read well at small point sizes on a 72 dpi monitor. If you are using PostScript fonts, be sure that you are using screen fonts of the right point size; it's easy to forget if you have ATM installed that PostScript fonts aren't actually scalable (i.e. you can't use a 10pt screen font at 18pt and expect it to look smooth; ATM gets around this by trickery involving the printer font, but this is of no use for READMEs). If you don't know what ATM is, don't worry about this bit; in that case you'll almost certainly be working with TrueType fonts anyway.

Bear in mind that embedding fonts and/or images into a SimpleText file (or standalone README) can quickly make a big difference to the size of the document, so try not to go too much overboard.

Check your spelling. This might seem really basic, but a poorly written/spelt README doesn't look good. Remember if using an automatic spell checker that it won't pick up on words that are spelt correctly but used wrongly (e.g. "its" versus "it's"), so you should still read the thing through yourself (or, even better, have someone else check it for you). For folks who aren't native English speakers, you have my sympathies (if you know any native English speakers, however, you might ask them to do you the favour of reading your text for you). (Editor's Note: try to avoid using Euro-English trash talk like Hamish. Words such as "favour" should be converted to "favor", "colour" to "color" etc. If you do not correct for such Scottish gutter-speak then Noah Webster himself will rise from his stinking burial pit and knuckle your nose around to the other side of your head with fetid, bony fists. Now, that said, can I find a volunteer that will let me hole up in the crawl space under their house so that Hamish can't find me?!?! - gls 10/4/2000)

ODE TO SPELL CHECKERS

Eye halve a spelling checker
It came with my pea sea
It plainly marks four my revue
Miss steaks eye kin knot sea.

Eye strike a key and type a word
And weight four it two say
Weather eye am wrong oar write
It shows me strait a weigh.

As soon as a mist ache is maid
It nose bee fore two long
And eye can put the error rite
Its rare lea ever wrong.

Eye have run this poem threw it
I am shore your pleased two no
Its letter perfect awl the weigh
My checker tolled me sew.

SimpleText Tips

SimpleText has the great virtue of being present by default on every Mac system under the sun. This makes it the right choice for non-standalone READMEs. (As a rough rule of thumb, if your map/scenario/patch/etc. itself is small, then keep your README small as well. Big projects generally require fuller documentation, so standalone READMEs are then a better idea for those.)

There are a few additional tricks that can be performed with SimpleText:

Colour can be added to text using a SimpleText add-on such as SimpleText Color Menu by Alessandro Levi Montalcini. (Editor's Note: This is only one place where you can find this, it is a fair bet that the big Mac ftp sites also have a copy of this. Be advised that this is shareware, 10 bucks American but it does more than add color. Added functions include Find and Replace commands, word counting, print margins, color icons and a Windows submenu inside Apple's SimpleText text editor. </plug> - gls 10/04/2000)

You can insert in line PICT graphics into a SimpleText document (in line PICTs will appear centered in the width of the document window). Where you want a PICT to insert, type alt-space followed by enough returns so that the image doesn't overlap the following text (text does not automatically reflow around images, unfortunately). Save and open the text file in ResEdit. Paste the PICT(s) in. Number them from ID1000 (i.e. 1000, 1001, 1002, 1003, etc...). Save, and then check back in SimpleText again just to be sure all is well.

To make the SimpleText file read-only, launch ResEdit and from the "File" menu do "Get File/Folder Info...", navagate to the SimpleText file, give it file Type 'ttro' instead of the usual 'TEXT' and save (obviously, you do this after you've finished writing it : ).