Example style guide by Jean Hollis Weber This document accompanies “Developing a Style Guide,” published at http://www.raycomm.com/techwhirl/styleguide.html, and includes a sample outline of a style guide. Some of the sections include some detailed sample text; others do not. Please note that the examples shown here are not necessarily the “correct” choices, or the “preferred” choices, or the “best” choices; they are simply examples of things to include. Your project may require additional items, especially if your writing will be used on a Web site. ------Style Guide for XYZ Corporation Follow this style guide when writing or editing materials to be published by XYZ Corporation, to ensure that documents conform to corporate image and policy, including legal requirements, and to improve consistency within and among our publications. Use this style guide as part of the specifications for your writing projects, along with: • XYZ Corporation Technical Writing Process Guide • XYZ Corporation Document Design Guide References This style guide lists decisions we have made for this company. It supplements several standard style guides, dictionaries, and other reference material. If you can’t find something in our style guide, look in these references or refer your question to the departmental editor. Dictionaries Merriam-Webster’s Collegiate Dictionary, Tenth Edition. Springfield, MA: Merriam-Webster, Inc., 1994, is the preferred source. Style Manuals This guide takes precedence over all other sources. The Chicago Manual of Style, 14th Edition. Chicago, IL: University of Chicago Press, 1993. Read Me First! A Style Guide for the Computer Industry. Mountain View, CA. Sun Microsystems, Inc. 1996. Grammar/Usage Guides For questions about grammar, consult any of the following: Webster’s Dictionary of English Usage. Springfield, MA: Merriam-Webster, Inc., 1989. Skillin, Marjorie E., and Robert M. Gay. Words into Type, 3rd Edition. Englewood Cliffs, NJ: Prentice-Hall, 1974. Strunk, William, Jr., and E.B. White. The Elements of Style, 3rd Edition. New York: Macmillan, 1979. Online References [Fill in as appropriate] Mechanics Graphic Elements Include drawings, figures, tables, and screen shots, whenever it seems useful or otherwise appropriate. Give each graphic element an informative caption. Refer to each graphic element at an appropriate place in the running text. For graphic elements used on Web pages, such as navigation aids, icons, photos, and other images, always include alternate text within the IMAGE tags. For example… Hyphenation Punctuation Use standard American punctuation. [If some of your writers are more used to British punctuation, you may need to add an example or two here.] Use of Language General Use short, simple, easy-to-understand words and sentences. Avoid the passive voice, except where appropriate. [You may want to include an example of an appropriate use.] In general, use the present tense and, where appropriate, the imperative mood (“Do this.”). Use strong subject-verb constructions. Avoid weak constructions such as “There are.” Be concise; avoid wordy phrases.

© Copyright 2002 Jean Hollis Weber Page 1 Use gender-neutral language. Capitalization Use sentence-style capitalization for headings. Capitalize and spell screen element names to match their appearance on the user interface. To avoid ambiguity, capitalize the first letter of each word (including articles, prepositions, and so forth) in the names of menus, dialog options, commands, fields, and other such elements, regardless of their capitalization on the user interface. Spelling Use American, not British, spelling; consult the preferred dictionaries. See the Terminology section for spelling of computer terms not found in the preferred dictionaries. Articles When using a term that includes special leading characters, choose the article that agrees with the way the term is pronounced. For example, the term “#include” is usually pronounced “include,” so the correct article is “an” (“an #include statement”). Units of Measurement Use American units of measurement. Numbers (in tables and text) Lists [capitalization and punctuation; treatment of nested lists] Terminology Abbreviations and Acronyms Generally Preferred Words Computer Terms Keyboard Key Names Choosing and Selecting Special Characters Content of topic types [particularly for online help, but also useful in any situation where multiple writers are involved] Overview topics Conceptual topics Reference topics Problem-solving topics Frequently-asked question topics Field-level help topics Procedural ("how to") topics Procedural topics provide step-by-step instructions on how to complete a user task. User tasks often involve the use of more than one window or dialog box. Users access procedural topics through the index, contents page, or links from window- or dialog-level topics. Procedural topics contain: • Task title (briefly identifies and describes the task procedure) • Phrased using terms that are familiar to users; users should be able to predict whether the topic matches their task goals just by reading the title • Begins with the gerund form of a verb (ending in –ing; for example, Submitting), followed by an object • Purpose of task or procedure from the user's perspective (a sentence or two that explains the task purpose, its usefulness, and the expected outcome or result) • Explains, in the users’ own language, why they would want to perform this task and how it relates to their work; focuses on user needs, not on how the application works • Answers questions like "What user problem does the procedure solve?" and "How does the procedure fit into the user's work?" • Prerequisite conditions or tasks that users must perform before beginning this task • If the prerequisite tasks have procedures of their own, link to help topics for those tasks • Step-by-step instructions or procedure (numbered steps that describe how to complete the task) • Begins with an infinitive tag (a short phrase beginning with "To"; for example, To submit the form:, To change an emergency contact:). The infinitive explains the purpose of the steps that follow.

© Copyright 2002 Jean Hollis Weber Page 2 • Each step describes a single action, such as clicking on a button, selecting an item, choosing a menu item, or typing text in a field. It is written as a verb followed by a noun phrase. • If there are multiple ways to complete an action, document a single approach and choose the approach that users will easily understand and learn. Provide cross-references to other topics that describe alternative ways to complete the action, but don't provide cross-references for common actions. • Procedural topics typically contain about 5 or 6 steps. If a procedure starts to exceed 8 steps, consider breaking it into two procedural topics. • What happens now? What happens after a user performs the task steps (outcome; results and follow up information)

• Related topics list Sample procedural topic

Title of help topic Adding a customer

Purpose To add a customer record:

Steps 1. Open the Customer Maintenance dialog by clicking a Customer button from any dialog. 2. Type the relevant details about the customer in the Customer Contact, Customer Address and Account Manager sections. You must fill in the following fields: • Customer Name (the full company name of the customer) • Customer Contact section: First Name, Last Name, Phone • Customer Address section: Street Number, Name, Type, Town, State, Post Code You may also fill in any other details in the relevant fields. 4. Save the record by clicking the Save button on the toolbar. What happens now? When you save the record, [product name] automatically assigns the Cust ID to the customer. Related topics Related topics Changing customer records Deleting customer records

© Copyright 2002 Jean Hollis Weber Page 3