IAN'S QUEST

by Ian Chadwick

Ian Chadwick is a technical writer and editor based in Toronto, where he lives with his wife, Susan, and their numerous pets, including Kepler, a dog who is laboriously being taught to play chess. Ian is also trying to get published a 120,000-word fantasy novel he just wrote.

Hooray! I recently got my upgrade of Empire (version 2.05) from Interstel, and I'm quite happy about it. Aside from several new commands and some improvements in the way the old commands worked, my favorite game is now significantly faster. Also, the graphics have been enhanced a teensy bit, improving the aesthetic appeal of the game. All in all, it makes Empire just that much better as an already terrific game. I have a whole panoply of ideas for them (helicopters, airborne troops, missiles, etc), but for now I like it just as is.

On the other hand, the changes are documented in a barely readable file on the new disk, incongruously called "README.DOC," significant only in the excruciatingly bad grammar and numerous spelling errors that crop up in it like crabgrass on my lawn. And that's not to mention the inexcusable use of the passive voice throughout. The author of this miniature horror, Mark Baldwin, has crafted a superb game, but he can't write English worth snail trails.

I know, I know, no one expects programmers to be able to write in English, but surely they have the technical skills to use a spelling checker.

There's no reason a single written page should go out of a software publisher without being checked for spelling and grammar. When I get one of these little models of illiteracy, I always feel like I'm a Cro Magnon in a world of Neanderthals.

Come on, guys, this is supposed to be a professional business, right? Is it too much to ask for you to assemble a document without at least spelling errors?

Of course, Interstel isn't the only company guilty of mangling the English language.

Take a look at Avalon Hill's new release, Spitfire: "as does the up and down direction keys." The correct form of the verb, as you might guess, is "do." (You did guess that, didn't you?) Also, they repeatedly talk about the "verticle speed indicator."

Michtron's GFA BASIC 3.0 manual is chock full of little errata, a myriad of annoyances, including "compare to" (compare with is correct), "variable MENU(2) to MENU(15)" (variables; it's plural), and "the Atari ST has two interface ports to connect a mouse and a joystick" (to which to connect...). Its author is guilty of overwriting to the extreme: "this function centers the object on the coordinates that are specified." What's wrong with "the specified coordinates"? "This command waits for a keypress on the key board": why keypress (one word) and key board (two words)? And where does the author think a key will be pressed? On the disk drive?

Sometimes the errata are more the result of sloppy editing than any inability to write the Queen's English.

Omnitrend's Paladin was rewritten from the Breach manual and as such, several oversights happened. For example: "carry a very weak sword". Weak sword? Probably they meant a "light sword". What about "fired a sword"? "Swung a sword" is more likely.

Not that these problems usually affect the programs, but they do seriously upset any modestly literate reader. How many times have you read about output being "printed on the printer" or "displayed on the screen"? Where else will something be printed or shown? Or the phrase "data is"—data is plural and the correct phrase is "data are". Or "your" instead of "you're"?

Then again, I've seen more than a few errors crop up in menu bars, dialog boxes, help files and the like. Atari's release of Microsoft Write had oodles of grammatical glitches in the program messages. I think the blame for this one lies with Atari, since Microsoft, not unlike Pontius Pilate, washed its hands of the program a while back.

The ST world isn't the only group at fault, by the way. I recently got Borland's Sprint word processor for my AT, and it came with a README file with eight 8.5 by 11-inch pages of corrections and clarifications to their manuals! And the English is only marginally better. However, ST publishers seem particularly prone to scale the heights of mediocrity in manuals.

In one sense, the inadequacy of documentation is good: it keeps the computer book publishers in business. However, a weak manual reflects more on the inadequacies of the publisher than on the ability of a writer to overcome them.

I've been writing and editing computer manuals for five years now and I've seen a lot of inconsistencies, passive voice, grammatical atrocities, spelling errors and just plain bad writing. Every time I come across errors in a professional manual, I shudder.

There are basic rules that should be followed by every software publisher before printing:

1. Don't let the programmers write the manual.
2. Use a spelling checker before printing.
3. Have the manual(s) read by qualified third parties and by potential users. Documentation should be as thoroughly beta-tested as the program, both to the quality of the language and the correctness of the instructions and descriptions.
4. Use professional writers and editors to write the documentation—at least as equally well qualified as your programmers.

Pretty basic stuff. You'd be surprised how many companies ignore these rules. I've been working with ISD's DynaCAD—a superb program—but the manual is, simply put, inadequate. Why? Because the programmer wrote it (and he's a nice guy too, but as a writer, he's out of his depth).

Really, all of this is inexcusable. Several hundred books on the art and craft of writing English are available at any good bookstore or library. Personally, I feel any technical writer who can't quote chapter and verse from the Chicago Manual of Style should be shot. Can't quote Strunk and White? Another one to the wall.

There are some good books available about writing documentation, including Hardwords/Softwords from Ashton-Tate and The Computer Documentation Kit from Reston. Apple publishes a decent style guide for Mac developers, but we pariahs have a hard time getting hold of it (besides, it's good but not great, and I have arguments with several parts of it).

The point is that there's no need for bad documentation. Of course, improved English won't help the terminally obscure manuals. How many times have you had your hair turn grey trying to uncover the meaning of an obscure error message the writers neglected to document, but it happens every time you try to save a file?

When I was at Batteries Included (BI), I wrote a basic style manual for writers, which never got published for obvious reasons. (Has anyone seen any BI products since the takeover?) Not that I'm an authority (I am, however, a technical writer by profession), but it's certainly something this industry needs. Perhaps it could be a place to begin an enlightened dialogue. I've considered redoing it and making it available (perhaps as a four- to six-part series of magazine articles). Any interest? Write to ST-Log and let them know. I'd be happy to do it.

Although I'm no longer writing the GFA BASIC column, I still get Michtron's product releases, so I should keep you up to date with their efforts. For those of you who haven't kept up with the state of affairs as far as GFA BASIC is concerned, Michtron has not kept still. And before I go any further, let me make one of those sweeping, unequivocal statements that always generate nasty mail: GFA BASIC is, as far as I'm concerned, the best programming language available for the ST, superior to C or Pascal. And it's certainly better supported by Michtron than any other company supports any of their languages, as far as I've seen.

Let's look at what they've been up to since GFA was first released. Unless noted, everything below is from Michtron.

With each release, GFA BASIC has improved, and by all means, that is true of the latest version. The language constantly improves and commands have been added, particularly in 3.0. Also, the manuals have improved considerably with each revision.

Training Reboot Camp is a beginner's guide with a silly title. It's a good introduction for the newcomer to BASIC, though rather weak in the advanced features.

The Programmer's Reference Guide, Volume 1 is a moderate to advanced level guide, containing lots of useful information, but the major failing is the lack of short examples. I simply won't type in 20 to 30 pages of code to try and learn a simple technique to include in my own programs. About one half of the book rehashes the program manuals, with only moderately more programming information than they provide. The rest contains very good information for technical data, especially in the GEM, AES and VDI areas.

GFA Vector, a 3D-graphics program for GFA BASIC inclusion, is slow, but if 3D graphics are your interest, this package is pretty good. If you don't speak German, you won't understand the remarks in the code. Some of the examples don't work and there's no way to tell why because of the language barrier.

The GFA BASIG Reference Card is an accordion-type card with all the commands, minimally documented. It's good if you know the language and need a reminder.

Abacus has released the GFA BASIC Quick Program Reference, which is a modest substitute for the program manuals, with some information not contained in them and other material left out.

The GFA BASIC Book is an intermediate programming tutorial and very good for learning the language. A significant improvement over the original manuals, it's my favorite of the lot.

GFA Companion is a resource construction set with a horrendously restrictive requirement not to publish any code produced by it, except if compiled. This makes Companion of limited use to anyone. There are several public-domain dialog box creation kits and example programs that will allow you to do about 80% of what this program accomplishes, without the nonsense about compiling code.

Okay, I said I got Paladin from Omnitrend, so I'd better say something about it. You liked Breach? You'll like Paladin. They're almost identical programs. Instead of grenades, you get orbs of fire; instead of missiles, you get crossbows—you get the idea. The differences between Breach and Paladin are mostly in the terminology. They are almost identical in function.

Yeah, they've thrown in a handful of magic spells (six spells altogether), but it's nowhere near the same sophistication as Dungeon Master.

Breach and Paladin also share the same serious programming flaw: only orthogonal movement is allowed, not diagonal. For the uninitiated, this means that if it costs five movement points to enter a square, the player has to move up one and across one, rather than move one diagonally, a total of ten movement points. However, the math of diagonal movement dictates that it should cost only seven points (rounded down), leaving three for other purposes. Obviously, Omnitrend has a terminal problem dealing with square roots. I can recommend a few basic books in math and algebra.

Paladin is a Conan-style magical adventure. The approach is tactical infantry style: lots of sword play, missiles and exploding weapons. The emphasis is on combat rather than on magic. The magic is restricted to things that suit combat and exploration. Forget trying to call up elementals, transforming your opponent into a duck, changing lead into gold. Paladin works on the "zap-em" level of magic.

Not that this is bad; it's merely limiting. It suits the game, and the scenarios are designed around objective-oriented situations, all involving a lot of hacking and slashing. It's not High Fantasy, but Paladin, like its predecessor Breach, is enjoyable and challenging despite the flaws. [A full review appears elsewhere in this issue—ed.]