informa
/
Production
Features

Manuals: They Can Be Good

Manuals are reviled as overblown, badly worded, uninformative dross that provide little or no help -- and unfortunately, this is sometimes true. But it doesn't have to be that way. Arnold Hendrick, game designer and manual writer, discusses some of the "dos" and "don'ts" of writing game manuals.
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).

Good manuals instruct the player, enhance the gaming experience, and explain away problems.

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.

Jane's game manuals feature a bounty of screenshots, with many callouts indicating the function of various on-screen indicators.

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:

  1. Title Page
  2. Table of Contents
  3. Introduction
    (If the publisher demands up-front hype for the game)
  4. Tutorial
    (Ideally designed to accompany a software tutorial)
  5. Game Operation
    1. Game Startup & Initial Options
      (Describes what each option means or does)
    2. Game Action
      (Subdivide by screens or concepts as appropriate)
    3. Game Results
      (Especially unique post-action screens and/or options)
  6. Background
    (In sections appropriate to the subject matter)
    (Information about various internal game rules and logic) (Hints about good play, strategies, tactics, etc.)
    (Historical background or fictional storylines)
  7. Game Data
    (Charts and tables of internal data useful to players) (Equations or formulae that might help players)
  8. Designer's notes
    (A short history of the game's development)
  9. Credits
  10. Legal Statements
    (Warranties, etc.)
  11. Glossary
  12. Index

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:

  • Skeletons
  • Zombies
  • Ghouls
  • Wrights
  • Liches

Numbered steps imply a mandatory sequence, like this:

  1. Place the CD-ROM in the drive.
  2. Wait for loading screen to appear.
  3. Press "install."

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 b

Latest Jobs

Sucker Punch Productions

Bellevue, Washington
08.27.21
Combat Designer

Xbox Graphics

Redmond, Washington
08.27.21
Senior Software Engineer: GPU Compilers

Insomniac Games

Burbank, California
08.27.21
Systems Designer

Deep Silver Volition

Champaign, Illinois
08.27.21
Senior Environment Artist
More Jobs   

CONNECT WITH US

Register for a
Subscribe to
Follow us

Game Developer Account

Game Developer Newsletter

@gamedevdotcom

Register for a

Game Developer Account

Gain full access to resources (events, white paper, webinars, reports, etc)
Single sign-on to all Informa products

Register
Subscribe to

Game Developer Newsletter

Get daily Game Developer top stories every morning straight into your inbox

Subscribe
Follow us

@gamedevdotcom

Follow us @gamedevdotcom to stay up-to-date with the latest news & insider information about events & more