Thursday, December 16, 2004


I've recently undertaken to learning Macromedia Flash. This has to be the most poorly documented piece of software ever. When I say poorly, I'm not saying that there's no documentation. I'm saying that the documentation that's out there is so poorly written and organized, that I gave up trying to use it. Part of the problem is that they don't just have one big document that gives you everything. There are half a bajillion little documents that give you some information.

The documentation looks like it was designed by a person who absolutely refuses to read any more text than will fit on a single page. This means that any idea or concept that's too big for one page is made so vague that it fits on one page, or it's split up into incoherent chunks.

I had a Computer Science professor who thought the same way. This was back in the day before professors had their notes condensed down into powerpoint slides. She wrote her notes out on an overhead projector longhand. She'd do this on transparency sheets. One concept to a sheet please. If it was a big concept she would start out writing small. Sometimes she would miscalculate, and end up having to cram the last bits of information in a jumble of smudged overhead marker at the very bottom right corner of the transparency sheet.

Anyway back to the Flash documentation and how bad it was. It was so bad that I went out and bought an external manual. I generally don't like manuals. I'd prefer something that I can print off at work and staple together. That way work picks up the tab. No such luck this time. Normally when buying manuals I go straight to the source of 90% of all good technical documentation. O'Reilly and Associates. If it's technical, they've written a manual on it, and in my experience it is often the best manual on the topic. This time I didn't find one to my liking. I started to ask around, and got a few suggestions. Normally I have several rules about manuals.

  1. Never buy a book who's title insults you. If you see a book title like "Personal Finance for Dummies" or "Practical Database Design for Flaming Idiots" or "Learning Perl for the microencephalic", just put the book down and walk away.
  2. Never buy a book with a past participle that starts in "de" or "un" in the title. That means no words like demystified, unleashed, debunked. That sets up entirely too high of an expectation. What if the subject isn't demystified or unleashed when I'm done reading? There's one exception that I make to this rule. As soon as the authors get off their asses and write them, I'm buying the entire UNFUCKED series. I'm sure that I could probably help provide source material, and might even be able to ghost write for them.
  3. The more authors, the worse the manual. I've found that between 1 and 3 authors is optimal. There are a few exceptions. This being the most notable. On the other hand, this book is almost guaranteed to suck.
  4. Never buy a manual with the author(s) picture(s) on the front.
  5. Only one adjective in the title. That means books like this one are out. If there are adjectives in the title they should be words like practical, simple and plain.

So anyway I broke down and bought a couple of the books recommended by my cow-orkers. The ones recommended seem to break most of my rules, but we shall see.

No comments: