ITS Style Guide

Writing Style

Here is some brief, general advice about the appropriate style for ITS documents and articles. The Resources page lists books and Web sites that have more extensive information on these topics.

Direct, conversational tone Use short, direct and precise statements, written in a conversational tone, as though speaking to a user asking questions. Don't sacrifice accuracy for the sake of brevity: include all necessary qualifications to statements. However, don't use too many qualifiers per sentence. Instead, use tables or lists.

Active Voice Use the active voice when writing. Your style will automatically become more brisk and energetic. In general, avoid writing in the passive voice.

Pronouns You may use you, your, and so on, but not I, except in personal narratives or reviews. The inclusive we, meaning ITS staff, should be used judiciously and only after using the full term. Consider the sentence:

The user should type this command exactly as shown, and he will get the correct results.

Although 'he' in the sentence refers to any person, not necessarily masculine, avoid such use by recasting the sentence to make it plural or imperative. For example:

Users should type this command exactly as shown to get...
or
Type this command exactly...

Don't use he/she , (s)he, or just she for such sentences: such usage simply distracts readers from the subject. Also, don't try a plural pronoun for a singular antecedent:

If a user types this, they will...

Here, "a user" is singular, but the pronoun "they" is plural.

Short words Carefully choose the shortest appropriate and accurate word. See The List of Words for a list of terms that may cause problems. Consult standard references about spelling, meaning and usage. Be careful about unusual words—some dictionaries include a definition without regard for the word's connotations. A thesaurus may be useful, but use a good dictionary to look up any word you have selected from a thesaurus.

Few words Avoid unneeded, superfluous, unnecessary, redundant, extra words.

Instead of...	Use...
the use of blasphemy	blasphemy
large in size	large
modular in design	modular
in order to	to

Also, be prudent with modifiers. Is a program highly modular or simply modular?