Manuals: They Can Be Good

Editor's note: This paper was originally published in the 1999 Game Developer's Conference proceedings.

In a study conducted some years ago among business software firms, it was reported that the only Silicon Valley employee with lower pay and status than a secretary was the documentation writer. Those responsible for game manuals often feel the same way.

Game publishing veterans know that no game is self-explanatory, no matter how what the programmers say. In-game help, tutorials, and programmed learning are all useful, but nothing beats pausing the game to flip through the manual quickly to find the meaning of an icon, a strange symbol, or just how to save the game! Most games take over a computer and its screen so completely that the game must disappear before a help file can appear. Furthermore, during those hopefully rare food breaks, a manual is more portable than a surround-sound, subwoofed, heavily peripheraled gaming machine.

Manuals are frequently reviled as overblown, badly worded, uninformative dross that provide little or no help. Unfortunately this is sometimes true. Manuals written too early describe half-implemented software that is later changed or removed in the final rush to production. Conversely, if the manual is written too late, writers madly write, cut and paste together whatever they can find in a desperate attempt to cover most issues, somehow. Publishers assign writers whose longest prior effort was a ten page college paper, then profess surprise at their inability to handle a 100-page manual job. Then there are those manuals who actually believe the programmers' claims about self-explanatory software, allowing them to take the easy way out with a manual that contains nothing more than "background" and "color" (i.e., bad fiction).

Every publisher bemoans the extra cost imposed by manuals. For a brief period some years ago Sierra (then Sierra On-Line) refused to include printed manuals in game boxes. Instead, the gamer just got a CD and some advertising leaflets inside a big box. The manual was in files on the CD, which could be read or printed out from your screen. This was a sales disaster. Gamers weighed and rattled the box, and judged the product wanting. Reviewers excoriated Sierra. None of these people just wanted heavier cardboard. For many, the mere presence of a weighty manual was an important feature, especially for complicated strategy, simulation or RPG games.

In other words, despite their moaning and groaning, certain gamers actually want a weighty manual, even if they don't read it first.

The Two Types of Manuals

There are two basic types of manuals.

1. The compact. Typically found in console-style action games, these manuals are designed to slip into the top of a CD jewel case. Compact manuals work well if the game has just one or two main screens, and one or two simple control sets - usually based on the buttons of a game controller. Compact manuals can appear in PC games. The Tomb Raider series is one famous example: these manuals can easily fit a 16-24 page format.

2. The tome. Normally found in complicated PC games, these manuals help the user understand a variety of cluttered screens with numerous controls. Talonsoft wargames, Interplay RPGs, or EA Jane's simulators are classic examples that all demand and receive tomes. Such complicated games require 50-100 pages just to explain all the screen graphics, controls, plus title, contents, boilerplate and an index.

Compact manuals can be expanded to greater size by adding background material such as hints, strategies, or storylines. This can quickly produce a 40-80+ page booklet -- what I call a "mid-range manual". Similarly, some games are too big for a "in the CD case" size and form factor. In both cases, the extreme brevity of the compact no longer applies. Therefore the greater rigor of a tome is used.

It is not uncommon to hope that a game's simple concept means a "compact" manual is possible. Later, of course, the multitude of controls, modes, and screens ruin these dreams. The person who decides how big a manual is necessary, and what's too much, should have written at least two compact and two tome manuals in their career. I believe that nothing matches real experience when making these decisions. Writers with experience in only one area can seriously misjudge the needs of the other. As for producers, those without the experience should seek advice from those who do have it.

Manuals & Product Sales

Most games are sold by word-of-mouth. The more people like a game, the more they "talk it up" to co-workers, on the Internet, and so on. Strong marketing may get a game into the stores, but only a good game zooms off the shelves and into customer hands.

Good manuals contribute to this success in three ways. First, they ensure that gamers can actually play the game. After all, you're never going to enjoy something you can't play! Second, a good manual can actually enhance the person's gaming experience. Third, a foresightful manual can pre-empt problems by explaining them away.

Goals of the Manual

1. Instruction. First and foremost, a manual tells the gamer how to operate the game. This is best done by designing the manual as a reference work. See "Manual as Reference" below for details.

2. Enhance the gaming experience. Manuals can illustrate and expand the player's gaming experience. A classic example was MicroProse simulations of the late 1980s. Those manuals included tons of detailed reference information about the various planes, tanks and weaponry appearing in the game. They also described real-world tactical tricks that could be used in the game to good effect.

This made gamers feel like insiders with special insights unavailable to "average" people. They learned the special tricks and appreciated the hints or strategies that helped them past difficult spots. The game made the gamers feel good about themselves. The manual played a large role in this. Compared to the difficulties of game programming and balancing, manuals are a remarkably cheap and easy way to improve the image of both a game and its publisher.

3. Explain away problems. More than once, a development team realizes that a certain feature or capability would be very nice, but there isn't enough time or money left to implement it! Almost anything beta testers demand, but can't be provided, falls in this category. A good manual will "explain" why the sensible and desirable features really aren't appropriate for the game. This can frequently minimize or even avoid bad press and internet flames.

For example, a flight simulator might reduce high-altitude visibility to maintain the frame-rate. Invoking "atmospheric haze" as an explanation sounds better than admitting the 3D hardware/software system with realistic visibility is unplayably slow.

Manual as Reference

When writing a manual, always remember that it is a reference work. Almost nobody reads the manual before they play the game. Instead, gamers play first then refer to the manual as they encounter confusing situations. Some people check the contents first, others the index, but eventually all start flipping through the pages, looking for a familiar screen shot, term or chapter heading.

Good manuals are designed to make reference easier. Bad manuals implicitly assume the reader will start at the beginning, read the whole manual, and then play the game. The largest cause of useless manuals is over-linear writing that buries what the gamer wants in endless pages of dense text, then demands the reader plow through it before anything is intelligible.

Think Visually

When writing the manual, imagine a gamer flipping through the booklet, looking for the specific screen, control or concept. The more visual "reference points" you provide, the faster they can "home in" and get what they need.

Use screen-shots with call-outs: This means a picture of the screen with each part clearly labeled. labels should be outside the picture, with lines or arrows pointing to the appropriate screen area. Labels superimposed on the picture obscure the contents underneath, and are easily mistaken for on-screen graphics!

For example, the frequently excellent Railroad Tycoon II manual has dozens of screen shots, but only one with a label, and that a mere four letter code inside the picture! This causes excessive verbosity in screen descriptions, as individual graphics and icons are described in painful detail. Furthermore, the lack of call-outs made it east to miss useful information, such as the Oil, Sand and Water gauges on the Instrument Panel on the train detail Screen (to retain the unfortunate capitalizations used there). Worst of all, the call-outs that did appear are meaningless letter codes, rather than immediately useful words or phrases.

On the other hand, Jane's F-15, one of the most complicated flight simulators ever made, has screen shots with call-outs every second or third page. With these, mere mortals have some chance of mastering avionics far more complicated than anything in RRT2.

Control illustrations: Console games with standard controllers always benefit from a "controller diagram page" with call-outs to each button and control device. Console game licensors normally provide standard versions of this illustration. Most require manuals use their standard terms for each button or control device, which promotes easy recognition and understanding.

PC games have a mouse and keyboard. Ideally, a well-designed Windows 9x game has every action available through mouse control. This means it can be illustrated with a menu, dialog, or button, even if a screen shot is unavailable or inappropriate. Unfortunately, many game designers are still stuck in the DOS mentality of keyboard-only inputs. Such games demand a fold-out keyboard diagram, while mouse- capable games with full compliment of keyboard shortcuts also benefit from a separate keyboard diagram.

Separating the Parts:
Operating Instructions, Hints and Background Data

Gamer questions or problems frequently involve how to operate something or interpret a screen. Later and separately, devoted fans seek background or data that helps them to be more successful. Therefore, a well-organized manual should separate information into three distinct sections: operating instructions, hints & background, and finally data (usually data tables).

Many writers find it more convenient to place the hints, suggestions, background, and data alongside operating instructions. Unfortunately, this simply conceals important basic information amid thickets of prose. Remember, the initial questions of most gamers involve operating instructions. Keeping these in one place, uncluttered and succinct, is well worth the effort.

In compact manuals, placing operating instructions right at the front is often the best policy. One admirable approach in its utter simplicity was Tomb Raider II's one-page list of the game controls, placed right after the table of contents. The authors rightly assumed that this "cheat sheet" of controls would answer most questions.

In complicated game manuals (tomes), most authors can't resist the temptation to provide background information along with the controls. They know gamers will want advice and help, and they know the developers/publishers need to rationalize certain decisions. The temptation to conveniently mix it all together can seem irresistible. Well, resist it. Such mixtures complicate a gamer's referencing, which makes a complicated game seem that much more complex.

Operating instructions must be clear and to the point. Information is easier to reference when it is neatly tagged, described and categorized. For example, in a combat jet flight simulator, descriptions of the multi-mode radar system can be dauntingly complex. The best solution is screen shots with call-outs to start the operating instructions, then a description for each call-out, then a description of what each applicable control does on that screen. Even if many modes share the same control, it is best to list each applicable control so the user understands what could be done. To avoid too much redundancy, the control description could be brief, with a reference to another page for details.

Detailed explanations of bar scans, refresh rates, and other electronic concepts do not belong in the operating instructions. These should be placed in the background & hints section, where the player can take Radar Systems 101 at their leisure. Naturally, the operating instructions will reference this section, so the player who really wants to understand more knows where to look.

Finally, neither of the above is where the game should list which radars are in which type of plane, or their technical specifications. All this is found in tables within the data section.

One of the most perplexing problems in manual writing is where to place game rules. That is, information about how the game works inside (i.e., within the software). In general, internal operation should be left to the background & hints and data sections. Alas, sometimes internal rules change how controls work, or even disable some while invoking others. In this case, a brief mention of the rule is appropriate, often with a reference for more information.

For example, the following would be appropriate in a strategy wargame. "You cannot choose Fire if the unit has no ammo (see Ammo Indicator on page 21, and logistics: Ammo on page 187, and Ammo Load Tables on page 205 for details)." Notice that a screen call-out was referenced, as well as background and data tables.

In some cases a competent description of game operation demands a rules explanation at that point. A common example is startup and configuration options. The user wants the manual to tell him exactly what occurs in each option. It is more sensible to oblige him, rather than make the entire section a series of references to pages in a "Background & Hints" section.

Procedural Organization

Within the operating instructions part of a manual, the best way to organize the material is procedurally. That is, the screens and controls first encountered by the gamer appear first, followed by the next screens and controls, etc. Those seen last, or very infrequently, should be at the end of the operating instructions section.

The primary exception is compact manuals. Here the gamer may be better served by an immediate presentation of the screen with call-outs, and/or a controller with call-outs. Startup options and other esoteric details can follow.

Rules vs. Examples

A cardinal rule in operating instructions is that any example must clarify a general rule, but never be a general rule. Lazy writers often use examples to present a concept or operating procedure. Unfortunately, when the gamer looks up the concept, they must wade through the entire example, then try to infer the general truth that might apply to their case. Rule through example greatly complicates the reference task, while an inappropriate example yields nothing but a hopeless puzzle.

Crafting a short, clear, general-purpose explanation to each screen element and each control is a non-trivial task. Given the short time and small funds allocated to most manuals, it is surprising that so many do a good job.

The Indispensable Index

A good index is required for any good manual. Even if gamers start by flipping pages, frustration may eventually send them to the index. The best indexes are always create by humans. Furthermore, it is really quite easy.

To create a good index, read through the manual from start to end. Every time a game-specific term appears, write it down with the page number. Every time a game concept is described, write it down with the page number. similarly note every screen title, every significant option on every menu, and every function with a special dialog or window. When in doubt, add an entry. When you're done, alphabetize the list and combine all entries for the same word into that word mention followed by all the page numbers. If your word processor can't alphabetize, import the file to a spreadsheet, which can sort entries alphabetically.

Manual indexing can be supplemented by indexing software. If this is available, use it afterward to catch references and additional indexing terms. Unfortunately, indexing software isn't smart enough to detect concepts as well as words, since the software isn't trying to understand the text. For that reason, indexing software an be a false crutch if used before you create one through reading.

Indexes are best done after the graphic arts person or team has set up the manual using desktop publishing software. Attempts to build indexes early, with hidden links within the word processor, invariably take more time than they save. On the other had, a game-specific style guide can be a gold mine of index material (see Style Guides, below, for details).

Structuring Sidebars

A sidebar is a short, self-contained article, often accompanied by a single picture or illustration, that appears next to the outside margin of the page. On narrow pages they sometimes appear at the bottom or top, instead of along the side. Pioneered by new magazines in the 1970s, sidebars were designed to present interesting ancillary information that relieves visual boredom in long text articles. They provide both a visual and intellectual "change of pace." Sidebars work poorly on pages with large illustrations, such as screens with call-outs.

In the operating instructions section, sidebars are most effective in presenting a larger example of play, especially examples accompanied by an illustration.

In the "Background", "Hints" and "Data" sections, sidebars typically contain incidental bits of historical interest, odd facts, or even sections of short fiction that support the game environment. For example, an RPG manual might have a series of sidebars, each with a different entry form a fictional adventurer's journal. The Railroad Tycoon II manual has a different, dated historical tidbit in each sidebar, with one on every page except chapter starts.

Boilerplate Text to Include

Every game must include certain legal statements regarding copyrights and trademarks. In addition, almost every reputable publisher includes a legal statement about terms of use. Often this is the infamous "warranty." Reading the fine print, you discover its real purpose is to prevent the user from presuming that any warranty, implied or actual, really exists!

A good manual writer allocates appropriate locations for these materials, or actually paste in the latest text, depending on the publisher's preference. Also remember to insert correct trademark and copyright statements in the appropriate spots, usually on the front and back of the title page. Unless specifically told, do not expect the publisher to automatically insert legal materials. Remember, if the publisher forgets, they invariably blame the author.

Detailed game credits should appear in the manual unless publisher policies prevent it. The best location is near the back, after any design notes and before the legal boilerplate glossary and index. Of course, certain egotistical developers and/or publishers may require the credits up front, before or immediately after the table of contents.

An Example of Tome Organization

Organizing a manual, especially a tome, is easier if you start form a well-tested pattern. The following general outline should serve most adventure, RPG, simulation and strategy games for PCs:

Writing Technique

The basic principles of writing are outline, draft, revise and edit.

A good outline helps insure that the manual covers all necessary points. It lets the writer concentrate on one section at a time. In large projects andrush situations, an outline allows different sections to be "shared out" to different authors. Compact manuals may be short enough to have an implied outline, but any tome requires an outline. The sample outline above requires at least one more level of detail, preferably two or more, before writing can begin. Any writer unwilling to use outlines has no business attempting a tome.

The first draft gets the information and concepts written down. Do not agonize over sentence structure of word choice. Concentrate on the information, even if its rough and wordy. In places where unfinished software requires guesswork, highlight the text in a special color for future review.

In the revision stage, the author revises the draft material, refining the wording for clarity. Remove unnecessary words, reorder sentences to enhance comprehension, and move around paragraphs to achieve a better sense of order. Professional writers always revise at least once, and many prefer a second or third revision "pass" to further polish and refine the language. At all costs professional work must never fall into the "first draft - last draft" trap.

Finally, there's the editing stage. All written work requires editing, and this is especially true for manuals, where the goal is not deathless prose, but clarity and comprehensiveness. After two or three revisions and author mentally supplies missing words and skims over spots - they understand the content all too well. Fiction writers handle this by letting a work sit for a few weeks or months so they can see it afresh. Game manuals cannot afford this luxury. It is far more efficient to hire an editor.

Good editors spot weak phrasing, catch spelling errors invisible to word checkers, check grammar better than any computer, and enforce a clear and consistent use of terminology. Editors do not need to be familiar with the game, but must be familiar with technical writing, including the importance of organizing the manual for reference rather than sequential reading. One sign of an inexperienced or unprofessional manual writer is a resistance to editing. In this field, good writers want good editors. No writer is perfect, and there is no perfect way to use the language. Even the best of writers can profit and learn from a good editor.

On the other hand, unlike the traditional publishing industry, it is best if the original author has the final say in any editing changes. Editors rarely understand as much about a game as the author. Therefore, some editorial changes may cause error. In such cases the author still needs to rewrite, since the editor clearly misunderstood something!

Brevity, Clarity, & Consistency

Short, simple clear statements are always best in manuals. Make declarative statements with few or no qualifiers. If a sentence communicates the same information without a word, cut the word. Be ruthless. If a prepositional phrase can be replaced by a single word, do it. Each unnecessary word obscures the meaning and increases the printing cost. In short, always cut with Occams Razor: the simplest explanation is always the best explanation.

Take this example (from a manual best left nameless): "If the loyalty of your spy is at a very high level then it is mostly likely that he will capture the foreign Kingdom and turn over its rule to you." Eliminate some words, simplify others, and you have: " A Spy with high loyalty frequently captures foreign Kingdoms for you." This also highlights the potential need for a second sentence describing what the gamer see when this happens.

Compact manuals should avoid long, running paragraphs of text. Actual operating instructions should be brief. Ideally, each paragraph should be tied to a screen call-out or control. Any paragraph with more than three short sentences is too long. Additional text should be pushed into the background, hints and data sections that appear after the operating instructions. These sections may be little more than a paragraph to a page each, given the stringent limits of 16 to 24 pages. The rest goes into the Hint Book.

Game manuals are improved by using simple words, short sentences, and brief paragraphs. Compact manuals should strive to stay at 6th grade reading level, and should never stray over 9th grade level. Tomes can use college-level vocabulary, since most teenage gamers seeking complicated entertainment are college-bound or reasonably well-read. Nevertheless, even tomes should strive for short, simple sentences. Two short sentences are invariably easier to follow than a single long one, with special attention to eliminating dependent phrases such as this, or parenthetical remarks (such as this one, which should have been a separate sentence long ago).

In traditional prose, writers avoid using the same word in successive sentences. In technical writing, including game manuals, it is vital to use one term for each concept, screen, and activity. Changing terms always confuses the reader. First check the software itself for terms, since programmers are loathe to change their wording to suit the convenience of manual authors. Instead of inventing new ones, use common computer terms such as click, drag, drop, press and highlight.

Organization Devices

Lists of features, or step-by-step instructions, are best when set apart from the textual paragraphs. Virtually all technical writing about computers uses this technique, usually with bullets.

Bullets imply a group, or a selection among items, like this:

Numbered steps imply a mandatory sequence, like this:

Text itself can be used as a visual aid through headings, subheads, and paragraph leaders. These work best with bold type. Most desktop publishing software supports headings and subheads, but paragraph leaders may not be supported. Nevertheless, paragraph leaders pay large dividends with users.

Each high-level heading organizes two or more subheads, and each subhead organizes two or more paragraphs with leaders. At each level there may be an introductory paragraph without a leader. One paragraph leader can introduce a series of related paragraphs. For example, here "Writing Technique" is the high-level heading for this section, and "Organization Devices" is the subhead.

Selecting headers and leaders is a fine art. Remember that gamers seeking a reference will scan the headers and the leaders, not the text within the paragraphs. Novices at visual text organization may need to write their text first, then add headers and leaders afterward. Many times the original outline will suggest headers and leaders, but only the most perfect of outlines can be used without changes.

Voice, Tense & Slang

Manual writing has become remarkably professional in 1990s, especially compared to PC games of the 1980s. Almost all writers use correct voice and tense, rather than carrying over the stilted and confusing terminology of 1970s vintage boardgames.

The correct voice is the second person singular. Manuals are written from the gamer's standpoint. "You" do this, "you" press a key, "you" see a screen, and "you" win the game. InEnglish this has the added advantage of being gender-neutral.

The best tense is invariably the present one, yielding the simplest and clearest possible word structure. "If you have infiltrated a Spy into an enemy fort it will sometimes happen that he will be promoted to General" is another tragic example that gains much when revised to read, "A spy hidden in an enemy Fort may receive a promotion to General."

Novice writers must be reminded that "Will is not your best friend - stop mentioning him all the time." In fact, doing a word search on "will," and eliminating every instance, is good practice.

Another good practice is avoiding convoluted tenses and verb forms. Searching on "had" and "ing" reveals most of these. This has the happy side effect of eliminating many common grammatical errors associated with complicated verb tenses.

Prose writers are exhorted to never use the common construction "to be". Technical writing and manuals live for it. Simplicity and clarity frequently make this verb the best choice. For those unfamiliar with the concept, "is" and "are," "was" and "were," and "will" are the present, past and future tenses of "to be."

A manual writer must know the difference between formal English, colloquial and slang terminology. Those who don't know the difference, but have the least suspicion of impropriety must check. Look up the word or phrase in an unabridged (i.e., big, thick) dictionary. If the word is not listed, it cannot be used. Word processor spelling checkers are insufficient for this task, since their word list is highly abridged.

Multi-word phrases and improper prepositions are more difficult to detect. Writers whose education did them a disservice must rely on a good editor, and study each correction carefully. Extensive reading also helps inculcate good language patterns. (Yes, turn off the TV and read a good book).

Aside from "good grammar," the reasons for avoiding slang are legion. Slang never translates well into foreign languages. In fact, it is frequently mistranslated, leading to considerable confusion. Slang common to one region, age group, or socio-economic class may be unintelligible to another. Finally, slang is imprecise, since it lacks formal definitions or meanings. In fact, the meaning of slang can and does change, or may lead to grammatical errors. Even if the game is full of obscure, obtuse slang, the poor manual writer must follow the straight and narrow path that maximizes understanding among all potential gamers.

In formal writing, such as manuals, contractions aren't desirable, and you're advised to avoid them. However, a number of very good manuals have made judicious use of contractions to impart a more friendly, personable tone. Contractions are most effective in tutorials or examples.

Style Guides

In the editorial sense, a style guide is a list of every "official" term used in the manual. It may also involve format specifications. A manual writer can operate with up to three separate style guides.

1. Implied style. The hardware and software environment of a game imply many common terms, such as controller, mouse joystick, folder or directory, menu, icon, shortcut, click on, etc. The wise writer only uses the most common, to avoid confusing gamers with unfamiliar terms. For example, not all Windows 9x gamers know the difference between a menu option and a "shortcut," and even fewer can accurately describe a "tool tip."

2. Publisher style. A publisher may have a standard style guide they require for every manual. For example, every game may need a "Quickstart" or a "Tutorial" section. Some years ago, one publisher of simulation games demanded that all references to "game" be replaced by "simulation" where possible, or "software program" otherwise. As a general rule, if the publisher does not specify a style, no writer can go wrong by using the Chicago Manual of Style (published by the University of Chicago Press).

Publishers of console game products under license from Nintendo, Sega or Sony must fulfill style requirements imposed by those firms. For example, various controls on the controller have specific, licensor-approved labels that must be used. Licensors can and will reject manuals, and thus the entire product, if the manual violates style requirements.

Publisher style guides frequently include instructions about what word processor software to use, and often include templates designed to ease the transition from work processor to desktop publishing software.

3. Game style and glossaries. Almost every game has a few specific terms. In compact manuals these are best defined in context (i.e., where they appear). In tomes, the quantity and frequency of specialized terms frequently makes this solution impractical. Most tomes benefit from a glossary, where all game-specific terms listed alphabetically with definitions. The best traditional location for the glossary is in the back, just before the index.

Experienced writers create the game-specific style, and incidentally their glossary, as they write the manual. This helps insure the same term is used everywhere. It also helps when rectifying terms with programmers or other contributing writers, who may have used different terms for the same thing. Even when a writer lacks a style guide, many good editors will create one, since part of their job is checking consistent use of terminology.

Style and Capitalization

In the early 1970s, Redmond Simonsen, Art and Documentation Director at SPI (then a major board wargame publisher in New York city) demanded that all game-specific terms be capitalized. SPI was the most prolific game publisher of that decade. His unfortunate decision rippled through hundreds of games, influence countless wargame designer/writers, and still influences designers and writers who have never seen or played an SPI game. Capitalizing normal nouns, regardless of context, is never correct English. Specialized terms can be italicized (set in italics) or surrounded in "quotes." Capitalization is completely unnecessary, although even this author must confess to falling under Simonsen's spell at times.

Production

It is well beyond the scope of this essay to discuss game booklet production. Ideally, an experienced graphic design professional should be involved in the conceptual design of every manual. Unfortunately, there are many people who know desktop publishing software, or have a passing acquaintance with HTML, but know nothing about graphic design. A reasonably trained professional knows the difference between sans serif and serif type (Helvetica or Arial are sans serif, Times is serif), how many points in a pica (twelve), how many picas in an inch (six in the computer age, slightly more in pre-computer typesetting), the difference between a gutter and a fly (the edge of the page along the binding is the gutter, the opposite edge is the fly), and can discuss intelligently the value and uses of negative space on a page.

Hopefully graphic professionals will also protect the printed materials from disastrous gaffs like the ink and paper choices that made the Baldur's Gate manual, reference sheet, and city map at best taxing, and at worst totally illegible.

Authoring Mechanics

Word Processors vs. Desktop Publishing vs. HTML Editors: Some writers prefer to write directly with desktop publishing software, or even using HTML editors, rather than a word processor.

Using a desktop publishing program for writing is never a good idea. Any author with sufficient training to do a good job in both fields should understand the value of doing the asks separately. Keeping the manuscript within a word processor has the added advantage that a graphics professional can "import" the file into various templates, experimenting quickly and easily with various designs. It is rarely as easy to reformat a document already set to a specific format.

HTML editors are more problematic, but many desktop publisher programs still have trouble importing or exporting HTML. Even if they can, style information is often lost, making the desktop publishing job much harder. The only reason to use an HTML editor is a manual that doubles as on-line help with hot-linked references. In this case the simplification of help file construction is balance against the increased difficulty in desktop publication.

Screen Shots: Whenever possible an author should provide screen shots, and in two forms. The first file is just the screen shot, nothing more. The second is the screen shot with call-outs attached. Any art or photo editing program allows this level of editing, as well as most word processors. The call-out version is purely a guide to the graphics people, telling them which call-out goes with which on-screen object. Beauty is not important here, merely clarity. To avoid accidents where a rushed graphics staff uses your call-out version, put a big, fat strongly-colored "FPO" (For Position Only) in the middle of the call-out version. A garish lavender is a useful color for this purpose.

Production Procedures

Desktop publishing software remains the best way to set up manuals for publication. The "industrial strength" versions are capable of outputting not only files acceptable to a printer, abut also Adobe Acrobat .pdf files, or web-browser-readable HTML files. When the game transitions from full-priced boxed product to the $10 bargain bin, then goes onto a compilation CD, or is licensed to an OEM, everything is faster, easier and cheaper if an electronic version of the manual can be put onto the CD-ROM.

Electronic Formats: Acrobat was a convenient standard in the mid 90s, but eventually HTML and ultimately XML will supplant it. Another advantage of HTML and (hopefully) XML is that users won't need special readers - a web browser will suffice. Best of all, instead of building a custom help file, HTML manuals could double as help files. In this scenario, clicking on the "Help" menu fires up the browser and loads the HTML/XML manual into a window on your screen. With some modest effort the contents and/or index could act as frame navigation tools.

Production Timetables

Time Estimates: It is impossible to write a manual at the perfect time. A decent manual writer needs about one week, plus one additional week for every 25 pages, plus a couple weeks for editorial and publisher changes. Then the desktop publishing people need time for their job, which should go four to five times faster than the writing. Thus a 200-page tome might take 11 weeks to write and edit, then need three (3) more weeks for desktop production. An ace writer who is familiar with the genre, has played alphas and early beta, and has acquired any reference data might be 20 to 25% faster, saving only 2 or 3 weeks out of the 14.

Blueline Fixes: Some producers skip the manuscript editing stage, then make extensive changes in the bluelines that come from the finished desktop production. These changes are invariably more complicated to make, and usually slow down the process more than they speed it up. Wise producers don't plan on any changes in the bluelines, reserving this review for last minute emergencies.

Timelines: Most games are far from finished 14 weeks before the master date. Manual writers complain that they can't do a good manual if the software is constantly changing. The author must either guess how the software might work, or write something uselessly ambiguous and vague. On the other hand, manuals done too late are written in such haste that important things are forgotten or poorly explained. Furthermore, language itself suffers when revision and editing is hasty to non-existent.

The only real solution is to write the manual at least 16-20 weeks in advance of the finish date, including the revision and editing. In fact, some background, hint and data material can be started even earlier. Then, as new betas appear, the author rewrites appropriate sections to keep the manual "current" with new versions of the game. The bug lists and new features lists are invaluable aids here. This allows manual adjustments to match the software, reducing lead time just 3-4 weeks, for a final edit (a few days) and the desktop publishing work.

Of course, this method requires producers with nerves of steel. After all, the producer must refuse to send the manual into "completion" until the game is 3 to 4 weeks from gold master. Many producers give in to pressure or optimism. They send the manual into finalization too early. This means they paid the extra cost (in author time) for the early start strategy, then squandered most of the advantage when the game drags on large, costly blueline changes are made.

Dual Computers: The most effective way to write the operating instructions is to have two computers. One computer has the game running, while the other is used for writing. Given the crash-prone nature of software during manual writing, no experienced author wants to run buggy or destructive software on their "work" machine. Writers unwilling or unable to use this "trick" frequently work at a slower pace or produce work of lower quality.

Blind Testing: If manuals and software are ready well before release, blind testing the manual can be very helpful. This test works like a marketing focus group. The manual author is required to sit in silence while a representative sample of users try to figure out the game, using nothing but the software and the manual - just like the final customer. Upon pain of death, the author cannot provide one word of help. Instead, the writer notes how people used the manual, what frustrated them, and what they failed to find. This frequently inspires improvements ranging from more index entries to minor rewrites.

There is no one, perfect way to use the English language. Good writers always seek better ways to communicate.

Arnold Hendrick's first published game (some WWII naval miniatures rules) was in 1968. he worked extensively in paper wargames, RPGs and miniatures rules until computer gaming arrived. Beginning in 1982 he has worked as designer and producer at Coleco, MicroProse, Interactive Magic, and currently Kesmai. With rare exception, he has written the manual for every game he designed or produced, from straightforward console cartridges to 200+ page military sim tomes.

He is currently designing and producing Jet Warrior: Vietnam, Kesmai's new flight simulator. The next generagion design is simultaneously played solo from a box, and massively multiplayer when online. He plans to write the manual himself, since despite more game development experience than the entire staff of some companies, moneymen just aren't burning up his phoneline with megabuck invitations to mastermind their product lines. If you need to make a megabucks investment in gaming, or just want more information on game design, production or manuals, his permanent email address is [email protected]