     |
 |
 |
 | | | | |
 |
|||
 |
||||||
          |
 |
 |
||||
|
Manuals:
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. _____________________________________________________ |
|||||||||||||||||||||||||||||||
Features
|
|
|