The passive is formed by joining a form of the verb to be with a past participle,
Too many thoughtless passives result in writing that is lifeless and dull. A paragraph can be filled with unnecessary and ineffectual passive construction.
For guidelines on capitalizing prepositions in titles and heads, see "capitalization" on page 10.
Future tense is often unnecessary.
To avoid sexist language:
page description language (PDL)
Spell out on first occurrence. parentheses
Parentheses deemphasize the material they enclose. For this reason, and because they are often overused, use them sparingly.
Enclosing explanatory material
Use parentheses to enclose explanatory or digressive material.
In the graphics architecture, TGrafDevice occupies a position one level below TGrafPort (the class that reduces a graphic hierarchy to a sequence of single geometries, each with a fully specified graphic state), and one level above TDisplay (the class that implements device drivers).
Use parentheses to enclose abbreviations, acronyms, and symbols when first mentioned in text.
an independent software vendor (ISV)
a local area network (LAN)
the pound sign (#)
Using parentheses with function names
Use empty parentheses to distinguish a function name in text. Never include the function arguments within the parentheses.
To run PrintReports( ), include it in your print routine immediately following the call to MakeReports( ).
Do not use parentheses for member function names.
After instantiating a TBar object, be sure to call its ReadyToPrint member function before you attempt to print the object with PrintReports( ).
For more information about member function names, see "naming identifier" on page 51.
Using parentheses with other punctuation
When using parentheses with other punctuation, always place colons and semicolons outside the parentheses.
The names of base classes begin with a T (such as TView); the names of mixin classes begin with an M (such as MCollectible).
Place periods outside the parentheses when what is enclosed is not a
complete sentence.
The opacity value describes a color's efficiency in absorbing light (how dark the color appears).
Place the period inside the parentheses when what is enclosed is a complete sentence and when this sentence stands on its own.
Install an application program by copying it from its original disk to your hard disk or to a removable disk. (A few programs have more elaborate procedures.)
passive voice
Although technical material is generally better presented in the active voice, passive voice does have legitimate and beneficial uses. For a discussion of the benefits of active constructions, see "active voice" on page 2.
so that the object of the action becomes the subject of the sentence:
The agreement had been broken in late February.
Used indiscriminately, the passive can weaken and obscure meaning. Find passive constructions by looking for forms of the verb to be: is, am, are, was, were, be, been, and being.
A new, safe method for catching tuna has been discovered by The Really Big Fish Co. Estimates of up to 75% fewer dolphin deaths have been made, but no details of the process have been released.
When it is rephrased primarily in active voice, it becomes a much more successful explanation.
The Really Big Fish Co. has discovered a new, safe method for catching tuna. It estimates that there will be 75% fewer dolphin deaths, but has released no details of the process.
pathname
Do not hyphenate. Always write as one word. pen width
Note two words. period
The period provides a full stop between complete ideas. 
Using periods
Use a period to end a sentence. Avoid ending a sentence with a verbatim command, as the reader might wonder whether or not the period is part of the command.
Rather than: In the CI, type
Use a period to punctuate some common abbreviations. In general, do not use a period with an abbreviation or acronym unless it can be confused with a word (such as in. for inch). For information on specific abbreviations or acronyms, see individual entries. servers/expserver.
Write: Type servers/expserver in the CI.
Placing periods
Place periods inside quotation marks.
When the default behavior is required, you can use these classes "as is."
Unless a full and separate sentence is contained within, place periods outside the parentheses.
All classes derived from MCollectible define streaming operators (operator>>= and operator<<=).
DrawContents creates a const pointer because it needs only read-access to the model (it does not modify the data--it only displays it).
personal computer (PC)
Always parenthetically introduce the abbreviation after spelling out personal computer. Make sure readers don't confuse PC in its common usage with the trademark IBM PC. (PC can also serve as an abbreviation for printed circuit or program counter.) pico (p)
(prefix) Represents one trillionth, that is 1/1,000,000,000,000. picosecond (ps)
Abbreviate units of measure when using them with a number to indicate a specific measurement. pixel
Originally an abbreviation for picture element, now used alone. plural
Most nouns change form when expressed in the plural. Use the standard dictionary plurals in most cases.
Note that the s is always lowercase, even if the surrounding letters
"'s, #'s,%'s
x's and y's
Ph.D.'s, M.C.S.'s (but CPUs, LANs)
are uppercase.
1 km; 100 km (not 100 kms)
appendixes (not appendices)
But note that matrices is used as the plural of matrix.
indexes (not indices)
formulas (not formulae)
antennas (not antennae)
For more information about forming the plural, see "apostrophe" on page 4.
Rather than: If the test(s) fail, the results are logged to a file.
Write: If one or more tests fail, the results are logged to a file.
p.m.
Use the abbreviation because it is more commonly recognized than post meridiem. Note lowercase letters in the abbreviation. pop up
(verb) pop-up
(modifier) Avoid using as a noun. positive (pos)
Spell out on first occurrence. pound (lb)
Abbreviate units of measure when using them with a number to indicate a specific measurement. possessive
See "apostrophe" on page 4.
PowerPC
(modifier) Note capitalization. Frequently used preceding the nouns architecture or platform. preposition
Try to arrange sentences to avoid ending with a proposition: consider clarity and idiomatic usage.
present tense
The tense for timeless action and general truths, the present tense is nearly always appropriate in technical documentation.
When you convert text from Unicode, the transcoder will convert text data from a TText instance into a string of characters.
Instead, write the sentence to phrase the general truth of this action in
the present.
When you convert text from Unicode, the transcoder converts text data from a TText instance into a string of characters.
Question uses of will to see whether they can be rephrased in present tense.
press
Use to describe the action of pressing a keyboard key (such as press Esc). See "type" on page 75. printout
(modifier, noun) private
Apply computer voice when used as a C++ keyword. procedure
Do not use this term to mean function or routine. For presenting procedures in documentation, see "step" on page 71. pronoun
Pronouns (such as she, he, or it) are words used in place of nouns. Two main problems exist with pronouns: unclear antecedents and the overuse of he or him for the third person singular pronoun (resulting in what some consider sexist language).
Avoiding unclear antecedents
To avoid ambiguity resulting from an unclear antecedent, make sure pronouns, such as this, that, they, them, and it have clear antecedents. Rewrite the sentence if the pronoun reference might be misconstrued, and use specific nouns rather than pronouns if there is any chance of confusion.
All the details are handled by threads from other subsystems. It is up to the caller to decide when it starts and stops, so it doesn't have to monitor its own state for termination conditions.
The antecedent is not clear. What starts and stops? What is monitoring?
Avoiding sexist language
Use gender-neutral pronouns and nouns whenever possible. See "gender" on page 27.
Rather than: An editor is meticulous about his work.
Write: Editors are meticulous about their work.
Rather than: Each employee should record his hours.
Write: Employees should record their hours.
Rather than: Ask your manager if he knows the password.
Write: Ask your manager for the password.
Rather than: The receptionist keeps her files here.
Write: The receptionist keeps files here.
Or: The receptionist's files are kept here. (This is an instance in which passive voice is acceptable.)
Avoiding we
Do not use we--in either the editorial sense ("we will now proceed") or in place of the company name ("we developed these classes"). protected
Apply computer voice when using as a C++ keyword. public
Apply computer voice when using as a C++ keyword. pull down
(verb) pull-down
(modifier) punctuation
See individual entries for more information about particular punctuation marks.
| Punctuation mark | Discussed on | |
| apostrophe | ' | page 4 |
| brace | { | page 8 |
| bracket | [ | page 8 |
| colon | : | page 13 |
| comma | , | page 14 |
| dash | ||
| em dash | page 21 | |
| en dash | page 22 | |
| ellipsis | ... | page 21 |
| hyphen | - | page 31 |
| parenthesis | ( | page 57 |
| period | . | page 59 |
| quotation mark | " | page 65 |
| semicolon | ; | page 69 |
push button
Do not use this term. Use command button instead.
[Contents]
[Previous]
[Next]
Click the icon to mail questions or corrections about this material to Taligent personnel.