To me, style is just the outside of content, and content the inside of style, like the outside and inside of the human body—both go together, they can't be separated.
—Jean-Luc Godard
Style is the correctness and appropriateness of writing conventions. It is an expression of the “look and feel” of information. Developing a style for technical information means following certain conventions, standards, and rules to ensure consistency. Style also entails making choices about tone, grammar, punctuation, and presentation.
Style and content are inextricably linked. Style distinguishes a piece of writing much as accessories such as white gloves and a top hat can distinguish an outfit or occasion. However, style isn't simply decoration that you apply to information; style helps users understand the information.
Generally, editors create style guidelines, which are rules collected in a style guide, for the department or company to ensure consistency across sets of information. Not only does this consistency lend credibility and corporate identity to a company's publications, it also helps to deliver information that users expect from a product or line of products.
Style guides exist for many types of industries. The newspaper industry, for example, has the AP Stylebook and the UPI Stylebook. The medical industry follows the American Medical Association Manual of Style. Many academic and technical publishing houses follow the Chicago Manual of Style. These style guides provide quick answers to questions of formatting, text labels, mechanics, punctuation, tone, use of graphics, word choice, and other conventions that writers and editors must follow.
Many companies that publish technical information develop specific style guides that cover conventions in finer detail than a guide like the Chicago Manual of Style. Some style guides don't deal with information such as online help and reference material that isn't read sequentially. Also, a specific project might have its own detailed guidelines that cover situations in which the project style expands on or differs from the primary style guide.
Most companies also produce specific templates and boilerplate text for various types of information. You can use templates and boilerplate text to ensure that your writing has consistent appearance, organization, legal text, and other required standard information.
Some of the suggestions in this chapter overlap with aspects of task orientation, accuracy, clarity, and visual effectiveness. The style guidelines about using an active style and appropriate mood, for example, reinforce the task orientation guideline about providing clear, step-by-step instructions. The accuracy quality characteristic extends also to using correct grammar. Clarity provides the rationale for many style decisions that become style guidelines. Templates and style guidelines can help ensure visual effectiveness.
To make information stylistically appropriate and consistent, follow these guidelines:
Use correct grammar.
Use correct and consistent spelling.
Use consistent and appropriate punctuation.
Write with the appropriate tone.
Use an active style.
Use the appropriate mood.
Follow template designs and use boilerplate text.
Create and follow style guidelines.
Using correct grammar is not as simple as it sounds. In speaking, people often use grammar incorrectly, and because incorrect grammar is so prevalent, you might not always know what is right and wrong. Nevertheless, you should verify that your sentences are grammatically correct. Making grammatical errors in your information lessens your credibility and the credibility of your company.
Incorrect grammar is not only confusing for English speakers, but it can also make the translator's job more difficult. A pronoun that is used incorrectly or a dangling modifier can produce translated information that is inaccurate or nonsensical.
Resolving grammatical issues is not just about correcting errors. Sometimes you need to decide whether breaking traditional grammatical rules is appropriate for your audience and purpose. For example, some grammar books still consider splitting an infinitive or ending a sentence with a preposition to be errors. However, some phrases are awkward if you don't split the infinitive or end the sentence with a preposition.
Consider the following original and revised sentences. Both sentences tell users to check that a file links to a column in a table. However, the original sentence follows the traditional, formal rule that states that writers should not end sentences with prepositions:
Original
Revision
The revision uses a contemporary, informal style. Because few people speak in sentences like the original sentence, many readers might think the original sentence is awkward or pretentious. Ending the sentence with the preposition sounds natural to most readers.
The following sentences show the awkwardness of trying to avoid a split infinitive:
Original
Second revision
The original and the first revision follow the formal grammatical rule that says do not insert a word between to and the verb, so the first two sentences might sound awkward to most readers. The second revision splits the infinitive to estimate, yet it is easier for most readers to understand. Knowing your readers and their needs will help you decide how to construct your sentences.
The following grammatical problems or issues often occur in technical information:
Sentence fragments
Incorrect pronouns
Dangling modifiers
Fragments are incomplete sentences, but using a fragment isn't always wrong. Headings, titles, captions, and some information in table cells are generally fragments. Moreover, your style guide might allow or mandate that you use fragments in some situations. For example, some style guides allow you to start a bulleted list with a fragment. However, do not write fragments within paragraphs.
Inappropriate fragments typically occur when writers misuse punctuation. Misusing the semicolon is the most common way that writers create fragments, as in the following original sentence:
Original
Revision
Semicolons are similar to periods in that semicolons must be followed by a complete sentence (except for items in a list). The part of the original sentence after the semicolon is not a complete sentence because it doesn't have a verb. The revised sentence correctly connects the phrase such as XML files and SQL files to the rest of the sentence.
Some style guides might suggest that you use a fragment before a bulleted or numbered list, as in the following example:
You can also use a full sentence to start the list:
Check your style guide about using fragments before lists, and always correct fragments within paragraphs.
Two common problems with pronouns occur with two of the relative pronouns (which and that) and with indefinite pronouns.
Relative pronouns introduce dependent clauses, which can be restrictive or nonrestrictive. Unlike restrictive clauses, nonrestrictive clauses can be dropped from a sentence without changing the meaning; they simply add nonessential information. Many style guides recommend using that with restrictive (or essential) clauses and which (plus commas) with nonrestrictive clauses.
Careful readers and translators recognize the distinction between that and which. If you don't use them correctly, your readers and translators might misinterpret your information.
The following sentence shows how misusing which can cause confusion:
Original
Revision
The original sentence uses the word which ambiguously. A user or translator might interpret the which clause as nonrestrictive and infer that the tool kit provides only one set of utilities. However, the writer meant to refer to a certain set of utilities out of many sets. The writer should have used that, as in the revised sentence, instead of which to show that the information in the relative clause is restrictive.
Using the relative pronoun which and commas indicates that a clause is less important and that the clause doesn't restrict the meaning of the term or phrase that it modifies. Remember to use commas around nonrestrictive clauses.
Another common error with pronouns occurs when a pronoun does not agree in number with the noun to which it refers. To avoid creating such errors, you need to know which pronouns are singular and which are plural.
Pay close attention to indefinite pronouns such as all, some, none, each, several, many, either, and neither. These pronouns can be troublesome because they are so often used incorrectly in everyday speech. Some grammar books also disagree on the use of none. Some grammarians consider none to be singular in all situations. Others treat none as singular or plural. None can be read as not one or not all. For example, the following two sentences can be correct depending on which theory you apply to the use of none:
If you think that the use of none might be misinterpreted, rewrite the sentence.
Remember the following rules when you use pronouns:
Each, either, and neither are always singular.
Few, both, several, and many are always plural.
All, any, most, and some can be singular or plural depending on the noun in the of phrase that follows them.
In the following sentence, the singular pronoun each must be followed by another singular pronoun:
Original
Revision
The revised sentence correctly uses its to replace each. However, not all indefinite pronouns are singular. The pronoun some can be singular or plural. For example, both of the following sentences are correct:
You must check the word in the of phrase that directly follows some to know whether to use a singular or plural verb.
A dangling modifier is a phrase or clause that cannot logically modify another element in the sentence. The sentence element that is supposed to be modified might not exist or is in the wrong grammatical form. Dangling modifiers are never appropriate in any type of writing.
Dangling modifiers are often created when writers combine an introductory participial phrase (-ing phrase) with a passive sentence. The following original sentence implies that the connections assembled the processor:
Original
First revision
You can also avoid confusion by using a full clause instead of the -ing phrase:
Second revision
The second revision is no longer ambiguous or confusing because it includes a subject and a verb. Readers know precisely who is performing the action.
As you write, be careful when you use participial phrases and passive sentences. Such combinations often produce dangling modifiers.
For information about misplaced modifiers and ambiguous phrases, see the clarity guideline “Place modifiers appropriately” on page 114.
Dealing with spelling can be more troublesome than correcting simple typographical errors. A word that is spelled inconsistently or incorrectly might confuse users and translators.
You will most likely need to decide how to spell new technical terms. Many industries and disciplines invent terms, some of which have more than one spelling. For example, the computer industry has created the following spellings:
database and data base
email, E-mail, and e-mail
filename and file name
meta data, metadata, and meta-data
on line, online, and on-line
runtime, run time, and run-time
In the following original passage, the writer spells e-mail inconsistently:
Original
Revision
The revised passage spells e-mail consistently. Users don't have to decide if the two different spellings of e-mail have different meanings.
Either spelling of e-mail might be acceptable, depending on the style guide. However, you should choose one spelling and use it consistently.
If a dictionary does not address particular terms, consider creating a style sheet that lists the spellings that you will use for your information and when. One spelling might be appropriate for a word when it is used as a noun (such as run time), and another might be appropriate when the word is used as an adjective (such as run-time).
Before you start a writing project, consider adopting a specific dictionary so that everyone on the team uses the same spellings. In most situations, using different, nontechnical dictionaries will not create inconsistencies, especially for established terms. However, because technical terms are constantly being added to the English lexicon, you can't assume that all dictionaries adopt the same new words at the same time.
If a mainstream dictionary doesn't address a particular spelling, you can also check industry-specific dictionaries such as Webster's New World Dictionary of Computer Terms. However, if you don't find the term in a dictionary, determine the most accepted spelling by checking sources in the relevant industry. See the clarity guideline “Use technical terms only if they are necessary and appropriate” on page 141 for more information about using technical terms.
In addition to new spellings, check the spelling of often confused words, such as principal and principle. In the following sentence, the word affect is used incorrectly:
Original
Revision
The revised sentence uses the correct term, effect. Most spelling checkers cannot determine whether words such as affect or effect are used correctly in a particular sentence. They can only flag it for the writer to check.
Consider the following often confused words. Make sure that you use them correctly:
accept and except
access and assess
advice and advise
affect and effect
capital and capitol
ensure and insure
its and it's
principal and principle
their, they're, and there
to, too, and two
whose and who's
your and you're
See the accuracy guideline “Use tools that automate checking for accuracy” on page 67 for more information about finding both spelling and grammar errors.
Most industries have adopted guidelines about how to use punctuation because no single authority for English punctuation exists that provides rules for every situation. Moreover, just as writing styles change over time, some of the guidelines that govern the use of punctuation also change. For example, the newspaper industry currently prefers not to use a serial comma before a coordinating conjunction, whereas in technical writing this comma is often mandatory.
Not all style guides agree on the use of punctuation. For example, non-American style guides typically say to use single quotation marks around new terms. As another example, many technical style guides suggest that you avoid using a pair of dashes to set off parenthetical information. In the following sentence, notice that the information surrounded by dashes is not important or restrictive:
Original
Revision
The dashes suggest that the information is important, and users or translators might not be able to determine if the information inside the dashes is restrictive or nonrestrictive.
Using the dash also creates an informal tone. In most cases, you can replace dashes with parentheses or commas if the information is nonrestrictive.
Combinations of punctuation can also be confusing. The most common combination is commas or periods with quotation marks. Both of the following sentences are correct, depending on the style guide that you adopt:
Before you start a writing project, consider how you will apply punctuation and mechanics. In addition to colons, commas, and semicolons, be especially careful about using the following punctuation:
Brackets
Em dashes and en dashes
Hyphens
Parentheses
Slashes
Single and double quotation marks (especially when they are used with commas and periods)
You can also consider how to use other mechanical elements such as numbers, symbols, and units of measurement. For example, should you spell out numbers or use numerals? How would you write mathematical expressions? After a number, should you spell out the unit of measure (such as megabyte) or use the abbreviation (such as MB)? And if you use an abbreviation, should it be preceded by a space or not?
Tone conveys how a piece of writing “sounds” or how it feels to the user. Tone expresses the writer's attitude toward the subject and the audience. An appropriate and consistent tone helps the user do the task, learn the concepts, or make the right decisions without needing to interpret your rhetoric.
The tone of technical information must be helpful: writing concrete and accurate information establishes a helpful tone. The tone must be direct: writing clear information establishes a direct tone. The tone must also be authoritative: writing task-oriented, accurate, and complete information establishes an authoritative tone.
Many tones are possible in technical writing. To achieve the tone that works best for a particular situation, you must understand the audience and the purpose for the information. For example, if you're writing a marketing brochure, you probably want to use a different tone than you would for a reference manual. As another example, a popular line of how-to books addresses novice users who want the basics foremost and details only at an easy-to-grasp level. The authors of this series of books write in a very friendly, humorous tone.
However, if you produce information that will be translated, avoid humor and sarcasm because they rely on specific cultural references and do not translate easily from one language to another. Be sure that you understand your users' needs before you use humor, sarcasm, or metaphors in your information.
In the following sentence, the writer is trying to be friendly while providing a requirement:
Original
Revision
In the original sentence, the writer tries to be polite and friendly. However, this tone makes the sentence wordy and unclear. The revised sentence is more direct and clearer than the original sentence.
Sometimes, writers use colloquial or idiomatic expressions to create a friendly, less intimidating tone. However, as with humor, colloquial and idiomatic expressions are difficult or impossible to translate accurately. Such expressions are also difficult for nonnative English speakers to interpret. To help translators create unambiguous translations, use a straightforward, noncolloquial style. Avoid idioms and slang, which nearly always cause problems for translators. In addition, be sure to write in such a way that the tone does not alienate nonnative speakers of English. Consider the use of slang and idioms in the original sentence:
Original
Revision
Although the original sentence tries to make novice users feel less intimidated by the technical jargon, the humor relies on the knowledge of a particular subsection of American usage. Words and phrases such as whole slew, geeky, and hang on cannot be easily translated in other languages. The informal, somewhat flippant tone might even be offensive in some cultures. Because the revision uses direct, formal English, it is less likely to confuse or offend users.
When you write for the Web, depending on the type of information that you provide, you can often use a tone that is engaging and friendly. A word of caution, however: People all over the world access the Web, so you should write for an international audience. Your Web pages can be lively and entertaining, while maintaining a tone that is professional and considerate of nonnative speakers of English.
The following sentence uses an idiomatic expression unnecessarily.
Original
Although bending over backward is an idiom that most native English speakers have heard and understand, it is difficult to picture it applied to a software tool.
The revised sentence expresses the same message as the original sentence in a style that is descriptive without being baffling. See the combined quality guideline “Applying quality characteristics to information for an international audience” on page 344 for more information about writing for international audiences.
Technical information is sometimes written with a pretentious tone. To be seen as credible and authoritative, some writers use complex sentences, abstract technical terms, and a wordy style. This tone can be confusing and intimidating. Consider the tone in the following sentence:
Original
First revision
The original sentence is not only confusing and wordy, but it is also pretentious. Using the pronoun one, passive voice, and long verb phrases gives the sentence a pretentious tone. Such a tone tends to alienate readers rather than engage them.
If the idea that everyone must know is not important, you can omit it from the sentence:
Second revision
Use the following guidelines when you write so that your tone is appropriate and consistent for a technical audience:
Write for an international audience.
Be helpful, concrete, and accurate.
Be direct and clear.
Maintain an authoritative tone without being pretentious.
Writing directly to users is the best way to convey information. Unnecessary passive sentences and complicated verb tenses can obscure the meaning of your information.
To help you create an active style for your information, follow these guidelines:
Use active voice whenever appropriate.
Write with the present tense.
Active voice puts the agent or performer of an action at the beginning of a sentence. If you want to emphasize who or what performs some action, use active voice. Use passive voice if you don't want to emphasize who or what performs the action. The following sentence is written in both active and passive forms:
Passive voice requires a longer verb phrase and places the agent at the end of the sentence or clause, or it doesn't mention the agent at all. In the previous passive sentence, the verb is are maintained, which is longer than the active verb maintains. The agent or performer of the action is administrator, which comes at the end of the sentence.
Passive voice is often difficult to understand because users might not understand who is doing the action. Consider the following sentence:
Original
Revision
The message in the original sentence is unclear because users might be confused about whether the sentence means that they can add up to 256 characters in the entry field or that something else, such as the program, adds characters to the field. The revised sentence clearly states that the user can type up to 256 characters.
Sometimes passive voice is appropriate. If the action or the receiver of the action is more important than the agent, use passive voice for the proper emphasis. The following original sentence uses active voice inappropriately:
Original
Revision
The original sentence emphasizes an action (saves) and an agent of the action (the system). The important part of the sentence is that the file gets saved; the idea that the system saves the file doesn't matter to the user.
Be careful with passive sentences in which the agent of the action is ambiguous and users must know who the agent is. The following original sentence doesn't tell users who or what performs the action:
Original
Does the user export the metadata, or does the system or program perform this task? If the writer meant that the user should export the metadata, the sentence should use the imperative mood, as in the first revision, or the indicative mood with second person, as in the second revision:
First revision
Second revision
If the system or program exports the metadata and the user must understand that information, the sentence should be rewritten accordingly:
Third revision
In all of the revised sentences, the user knows exactly who or what performs the action.
Present tense verbs help you keep your writing style active and direct. You should use the present tense for your verbs whenever possible. The present tense is easier to translate and more engaging. Use the past or future tense only when the present tense would be misleading or illogical.
In the following original sentence, the writer uses the past tense unnecessarily:
Original
Revision
Although both sentences use passive voice, the original sentence uses the past tense unnecessarily. (The passive voice is appropriate because users don't upload the Web pages. The installation program does this automatically.) When the pages are uploaded is not important. The revised sentence uses the present tense appropriately.
Unless you have a good reason to use the past or future tense, always write in the present tense.
Mood describes the communicator's attitude toward or relation to the action. Verbs can express the indicative, imperative, or subjunctive mood. Writers of technical information use mainly the indicative mood for conceptual and reference information and the imperative mood for task information. The subjunctive mood, which expresses wishes, doubts, and desires, is rarely appropriate. A subjunctive statement can confuse users and can be difficult to translate into languages that do not have the equivalent verb quality.
The indicative mood is used to state facts and opinions, whereas the imperative mood expresses a command or request. With its implied you, the imperative mood addresses the user and clearly identifies the action that the user should perform. The following sentence is from a procedure:
Original
First revision
Second revision
The original sentence does not tell the user to perform an action. It is also written in the passive voice, which makes the sentence more confusing. The first revision is an improvement because it brings the user into the picture by using the second person and the indicative mood, but this revision simply describes an action; it doesn't tell the user to do anything. The second revision shows the instruction as it should be: in the imperative mood.
Use the indicative mood to state facts and the imperative mood to instruct the user. For more information about using the imperative mood in task information, see the task orientation guideline “Provide clear, step-by-step instructions” on page 36.
Using the same template across sets of information, such as for related products, ensures that the information maintains a consistent structure and appearance. Creating a template for every new project is a waste of effort.
Using boilerplate text ensures that your legal notices or other standard information is accurate and complete.
To save time and to prevent possible inaccuracies in your information, follow these guidelines:
Create and reuse templates.
Use boilerplate text to ensure inclusion of necessary information.
A template is a collection of styles or tags that define the structure and appearance of a document. Some templates offer only a minimal number of styles, so writers, editors, and visual designers must define styles as needed. Other templates are very rigid and don't allow writers to redefine items such as fonts, tabs, character sizes, or line spacing.
Minimally defined templates might allow writers more flexibility to present information creatively, but writers run the risk of delivering information that is inconsistently presented, which could be confusing and distracting to readers. However, even though rigid templates keep writers from changing styles to fit particular needs, these templates also ensure consistent presentation. If you are involved in creating templates for your information, carefully consider the styles that you adopt and decide whether writers should be allowed to deviate from those styles.
This book uses a specific set of styles. For example, the styles define the fonts and sizes for each heading and line of body text, the line spacing, the width of the margins, and the appearance of tables. Using a template allows writers to concentrate on content instead of worrying about layout.
For more information about maintaining structural consistency throughout your information, see the completeness guideline “Use patterns of information to ensure proper coverage” on page 90 and the visual effectiveness guideline “Use visual elements logically and consistently” on page 295.
Boilerplate text is standard text that can be inserted into documents with few or no changes. Most companies use boilerplate text for legal and copyright statements, trademarks, or warranty clauses. If your information will be published outside your company, you will probably need preapproved legal text, notices, and contact information. Not adding the correct boilerplate text can create serious legal problems for your company.
The following passage is a portion of legal boilerplate text from an InfoDBase information unit:
Legal boilerplate text is generally complicated information that is provided to protect the company from litigation. You are rarely allowed to change or remove such legal information. Technical editors or lead writers should ensure that boilerplate text is current and appropriate for specific products or services.
In addition to boilerplate text, most industries mandate that you use warning or caution labels only for specific situations. Some companies provide boilerplate text for danger, caution, warning, or attention labels. For example, most computer software style guides say to use caution labels only when an action could physically harm the user or others.
The following passage uses text labels inappropriately. The style guide for the InfoDBase product requires that caution notices be used only for situations that are hazardous to people and not to insert an exclamation point. The style guide also specifies that attention labels be used to indicate that an action might cause loss of property or data.
Original
Revision
In the original sentences, the writer uses different words inconsistently to describe potentially serious information. The revision uses the correct label, text, and highlighting as specified by the product's style guide.
Before you write, consult your style guide about when to use text labels, highlighting, and boilerplate text to warn users, make recommendations, or provide notes. Use boilerplate text and text labels when appropriate. Do not interchange text labels or highlight them differently from one place to the next.
Style guidelines, whether they come from a style guide or a style sheet, help you and your team consistently apply specific conventions to your information. For example, style guidelines can specify what text to highlight, what tone to use, or what spellings to use. A style guide might contain hundreds of entries that describe how to deal with everything from apostrophes to Web addresses.
Information presentation that is not uniform is distracting and potentially confusing for readers. Style guidelines help ensure that writers working on related information do not introduce variations that will create inconsistent presentation. Before a writing project begins, your team should create or adopt style guidelines.
The easiest way to prepare a set of style guidelines is to adopt a published style guide. If necessary, the lead editors and writers can adapt specific guidelines in the published style guide for their company or projects.
To help everyone on your project follow style guidelines, you can create quick-reference style sheets. A style sheet is generally shorter than a style guide, and it provides a list of project-specific style guidelines. In addition to expansions on the style guide, a style sheet can also document deviations from the style guide.
For example, your style guide might say to keep your tone formal, direct, and neutral. However, you need to write information that will be included in marketing materials, so you want to provide lively, less technical information. Therefore, your style sheet for marketing information might say to use contractions, metaphors, and even humor.
Figure 14 on page 204 shows the relationship between style guides and style sheets. Externally published style guides typically provide the foundation for internal or project-specific style guides and style sheets.
Style sheets and style guides can be arranged alphabetically, by style category, or any other logical arrangement. The more writers and editors can do before actual writing begins to ensure consistent style across information, the better the result will be, and the less copy editing and updating that will be required.
If you need to decide what specific conventions to use for a set of style guidelines, such as whether to allow and/or, whether to capitalize Web, or whether to use mice as the plural of mouse (the computer device), consider the following advice:
1. Consult relevant authoritative sources for similar situations. Check more than one source to see whether authorities disagree on the subject.
2. If you find no obvious similar situations, isolate the underlying issue. Look for precedents that apply to the issue or for guidelines that define style conventions in the general area.
3. Consider the consequences for users, particularly translators and non-native speakers of English. Are users likely to benefit from this style decision? Could they be confused by it and misinterpret the meaning?
4. Consider the ease of carrying out possible style decisions. How easy would each be to apply, probably by people other than just yourself? Is the reasoning straightforward, or does it have some exceptions?
Whatever your source for style guidelines, if you follow them consistently, you'll provide your users with a reliable presentation that won't interfere with their ability to use the information easily.
In addition to checking and deciding on conventions of grammar, punctuation, spelling, and tone, consider the following guidelines:
Provide practical and consistent highlighting.
Present list items consistently.
Use unbiased language.
When you use highlighting consistently and predictably, users can pay attention to the content. They don't need to stop and think about why a certain term is in boldface and another is in italics, or what the difference is between entering a command that is displayed in lowercase and one that is displayed in all capital letters.
Assume that each of the following instructions is from different parts of a product's information:
Original
The problems are obvious when you look at the original instructions together. The word enter appears in three different styles, two of which apply to the same usage. The second and third instructions use the same highlighting (monospace) for different situations. The writer uses different types of highlighting (all capital letters plus quotation marks versus a capital letter plus italics) to refer to a key. Even if the writer provides an explanation of highlighting, these discrepancies are confusing and might cause users to make mistakes.
Revision
The revised instructions reduce the amount of highlighting and do not use conflicting styles. Users who quickly scan the instructions will not stumble over the confusing highlighting in the original text.
The sample style sheet in Figure 15 describes how to apply different types of highlighting for the InfoDBase product information:
Guidelines for list items vary among style guides. However, many technical style guides recommend the following guidelines for lists:
Use a complete sentence for the list lead-in sentence unless your style guide specifies that you should use fragments.
Include at least two items in a list.
Make list items parallel.
Start each list item with a capital letter.
If one list item ends with a period (because it is a sentence), use periods on all items.
If none of the list items are sentences, don't use periods.
The following list violates several of the previous guidelines:
Original
The metadata object catalog can contain:
Dimensions
hierarchies that can be from any dimension
cubes
facts.
The original list does not use a complete sentence for its lead-in sentence, it does not use capitalization and punctuation consistently, and it is not parallel:
Revision
The metadata object catalog can contain the following objects:
Dimensions
Hierarchies (from any dimension)
Cubes
Facts
In the revision, the introduction is a complete sentence, each list item starts with a capital letter, and no list item uses a period.
For more information about presenting lists, see the clarity guideline “Keep lists short” on page 129.
As more and more products are marketed globally, you should pay attention to biased language in your information. Avoid making assumptions about gender or race in your writing.
For example, suppose that a scenario includes a list of fictitious names, phone numbers, and e-mail addresses. The following table includes only male Anglo-Saxon names:
Original
Revision
Even though the names in the table don't refer to real people, the revised names to some extent reflect the diversity of an international audience and avoid the sexism of an all-male list.
Include references to gender or race only if they are relevant. The following sentence is acceptable in scientific information:
Also, be careful with references to occupations. Don't write a sentence so that you imply that all nurses or administrative assistants are women, or that all doctors and programmers are men. The following sentence makes an assumption about the gender of an administrative assistant:
You can revise the original sentence by changing the nouns and pronouns to plural:
Revision
When you correct sexist language, avoid using he or she as in the following original sentence:
Original
Instead of using he or she, use plurals, the imperative mood, or second person to restructure the sentence as in the following revised sentences:
Revision using plural
Revision using imperative
Revision using second person
Or you can write the sentence as an example by using a fictitious person's name:
Revision using a person's name
Depending on the context of a particular sentence, you can use one of the styles shown in the revisions to avoid gender-specific pronouns.
When you revise information such as this, ensure that you don't pair a singular noun with a plural pronoun:
Although many people speak this way, this sentence is grammatically incorrect because the plural pronoun doesn't agree in number with its singular noun. See “Correct pronoun problems” on page 185 for more information about how to correct pronoun problems.
A consistent and appropriate style helps users understand information. Effective style is transparent and doesn't hinder users' understanding of the information. Users notice style only when highlighting, punctuation, or spelling is used inconsistently; when sentences are ungrammatical; when the tone is inappropriate; or when legal notices are incorrect. When users pay attention to the style, they probably do not pay attention to the meaning of the information.
Use the guidelines in this chapter to ensure that technical information has the correct and appropriate style for your audience. See the examples in the chapter for practical applications of these guidelines.
When you review technical information for correctness and appropriateness of style, you can use the checklist on page 212 in two ways:
As a reminder of what to look for, to ensure a thorough review
As an evaluation tool, to determine the quality of the information
You can apply the quality rating in the third column of the checklist to the guideline as a whole. Judging by the number and severity of items you found, decide how the information rates on each guideline for this quality characteristic. You can then add your findings to “Quality checklist” on page 387, which covers all the quality characteristics.
Although the guidelines are intended to cover all areas for this quality characteristic, you might find additional items to add to the list for a guideline.
