|To meet Wikiversity's quality standards, this article may require some cleanup.|
Please discuss this issue on the talk page, and/or replace this tag with a more specific message. Editing help is available.
Back to Technical Writing Level 1
Technical Writing Videos
Williams Technical Writing Videos
Free short videos are available from TWFred (an author of Wikiversity's Technical Writing Course) explaining technical writing strategies and techniques. These videos complement the contents of this Wikiversity course. Topics include the following:
- Using Active Voice
- Structuring Descriptions, Steps, and Outcomes
- Avoiding Ambiguity and Exaggeration
- Choosing Terminology
- Writing for User Personas
- Inform (educate) the user.
- Write clearly, using words the audience understands.
- Compose simple, active voice sentences.
- Understand the audience and speak directly to the reader.
- Use active voice, appropriate grammatical person, present tense, and the imperative mood.
- Determine if the text requires a change in grammatical person or past tense, future tense, and/or declarative mood.
- Avoid unnecessary repetition, redundant jargon, and passive voice.
- Evaluate your writing: write, review, and repeat.
Important information first
Important information at the beginning of a sentence makes it easier to understand.
- The unwise walking about upon the area near the cliff edge may result in a dangerous fall and therefore it is recommended that one remains a safe distance to maintain personal safety.
- Danger! Stay away from cliff.
Use your audience's vocabulary
Good technical writing improves the reading experience. Use synonyms for "technical" terms to make the reader's document search more effective.
Source: by Barry Millman, Ph.D.
Understand your environment
Some business environments don't understand the technical writing style, insisting on passive voice and artificial formality. Modern technical writing directly addresses the reader in an unpretentious way.
Good sentence structure helps convey information. Try to keep the most important information towards the beginning of the sentence.
- Furthermore, large volumes of water are also required for the process of extraction.
- Extraction also requires large volumes of water.
Long sentences tax the brain and make remembering information difficult. Strive to keep sentences under 16 words. Split long sentences into two or more chunks. A sentence that lists three or more items may work better as a bulleted list.
The most basic sentence is a simple sentence with only one clause. Evaluate each sentence to ensure it contains sufficient information.
In the U.S., periods and commas usually fall inside the quotation marks. In the UK and most other countries, terminal punctuation usually goes outside the quotation marks unless part of the quotation. This style (sometimes called logical punctuation) is also permitted in American writing where precision is necessary, e.g. in presenting computer code and commands, or in textual criticism.
Five rules of concise communication
Avoid the obvious
Understand the audience's technical level. Know what terms they understand and what terms you must define.
When reading a piece of technical writing, the audience does not benefit from elaborate prose. They just need information on how to perform a task. Avoid using padding, or filler. Don't use phrases such as, kind of, sort of, and essentially.
Avoid redundant prepositional phrases
Prepositional phrases, the combination of a preposition with a noun phrase, are among the worst offenders in making text long and tiresome to read. Often, it is possible to replace an entire phrase with a single word.
- Use now instead of at this point in time.
- Use suddenly instead of all of a sudden.
Write short, succinct sentences. Never say, "...as has been said before," "..each and every," "...point in time," etc. Avoid "...in order to," especially at the beginning of sentences. Every word must contribute meaning to the sentence. Technical writing is information delivery.
While it is good to have a wide vocabulary, technical writing is not the place for showing off linguistic abilities. Technical writing is about producing clear, plain instructions for a specific audience.
|George Orwell's general writing rules work for technical writing:
Exceptions for technical writing:
Look at the Basic English ordered word list.
Use active voice
Active voice clearly shows the actor in a situation. When we read active voice, we know who does what to whom. Active voice is shorter and more interesting to read. Active voice is the standard for technical writing.
Passive voice obscures the actor—sometimes deliberately, as in, "Mistakes were made." Passive voice is ambiguous and often leaves out important information. Who made those mistakes?
You can identify the passive voice easily. Sentences that have the word "by" are almost always passive. Past-participle verbs—"was eaten," "is driven"—are usually passive. You can always rework a passive sentence to turn it active. Often, you just put the actor first.
Common intransitive verbs
The following verbs cannot be used in passive voice: appear, arrive, come, cry, die, go, happen, occur, rain, sleep, stay, walk.
Understanding present tense
Computers have no past, and no future. Everything happens in the present as a direct result of some event, usually caused by the user. As each event takes place, the computer has a reaction. Each of these events happen in the present, so good technical writing uses the present tense almost exclusively.
First, second, and third person refer to personal pronouns that reflect a point of view in singular and plural forms. Each "grammatical person" can be written in subjective case, objective case, or possessive case.
When writing or editing technical content, consider the sentence or paragraph's meaning. The two examples below demonstrate common uses of third and second person.
Example: Third person - active voice
The second person point of view addresses a reader or listener directly. Second person addresses the reader, the person your writing speaks to ("you" for both singular and plural).
Here is an example of the imperative mood with the pronoun your:
Plain language specifications generally specify that you use contractions where appropriate. Do not use irregular contractions, or contractions that reflect future tense or passive voice—e.g., "...the motor'll start."
Readers process and understand short, active voice sentences. Remember that instructions you provide the user must indicate: who, what, where, and how to perform the action.
Workers should tighten the chuck with great care because incorrect tightening may result in damage to the drill bit.
Tighten the chuck carefully to avoid damaging the drill bit.
Avoid ambiguous sentences
Do not write sentences that the reader may interpret in more than one way.
Write for application consistency
Commonly, steps in a procedure or task follow the navigational structure of the application left to right, top-down. Each step must include the menu commands, or dialog box and field names in the sentence. The top-down method determines the "big picture" (global view) of the application first and then defines its features in detail. Note, based on the language we may read right to left.
We interact with computers in a variety of ways. You can select anything on an application user interface by selecting it using a keyboard or mouse. It is important to use action verbs and software terminology correctly.
The most frequent verbs used in software are:
Use of an action verb in a sentence (bolded words):
Use of menu actions and commands in a sentence:
Make users aware of where they are in the application. If there is more than one method to perform an action, use the most common method. Define "what, where, and how" in each step of the task or procedure. Describe menu items for the current task left to right, top-down.
English provides no dedicated pronoun for the gender-neutral third-person singular. The word "it" refers to animals or inanimate objects. Writers often use the gender-ambiguous plural pronouns: "they," them," and "their," to describe individuals of unknown gender.
In technical writing, the gender-neutral pronouns, they, them, or their, are preferable to the verbose he or she/his or her/him or her. If a sentence seems awkward, try to avoid the issue: leave out the pronoun or use second person imperative. These examples assume the operator is the audience:
The operator must turn in his or her cycle log each Friday.
The operator must turn in their cycle log each Friday.
Turn in your cycle log each Friday.
Writing for translation: Use gender-specific pronouns when writing for a language that uses personal pronouns that differ according to gender.
Just as in regular text, it is important to punctuate lists correctly. If the list is made up of phrases, capitalize the first word of each list item. Do not end each list item with a comma or full-stop (period).
The new Skoda Fabia has the following benefits:
When items are complete sentences, begin with a capital and end with a period.
The new Skoda Fabia has the following benefits:
List items are sometimes an initial phrase followed by a complete sentence. In that case, use capital letters and full stops (periods) for the phrases as well as the complete sentences.
Subject matter is important. Remember that warnings come first. Apply warnings to any documentation that includes a task or procedure that causes damage to life or property.
Part of our task as information specialists is to write in a tone suitable for the audience. In writing for educated and experienced engineers, an informal tone is inappropriate. Most technical writing requires a reasonably formal style. When deciding on style and tone, audience, subject, and purpose are the main considerations.
Audience awareness dictates style. As we are writing for professionals we must write professionally, in a reasonably formal style.
Our purpose is to inform, not to entertain. So our writing must be informational.
When writing for audiences that include non-native English speakers, it is important to write simple, straightforward sentences and avoid colloquialisms. Some industries have adopted a “Simplified English” that consists of about 1000 words, each with a single meaning. Be aware of any relevant simplified English for the target industry, so you can write text that the audience can understand.
Articles in English present some of the most difficult aspects of grammar. Here are the rules.
Articles in English are invariable. They have one form regardless of the subject: "the" is always "the," and refers to:
Use 'an' with nouns that start with a vowel sound (a,e,i,o,u) and 'a' with nouns that start with a consonant sound (letters that are not vowels):
The indefinite article:
refers to something for the first time:
An MGC is a "Media Gateway Controller." The MGC controls all activity on an IP phone network.
with nationalities and religions:
with names of days:
to refer to a kind of, or example of something:
with singular nouns, after the words 'what' and 'such':
meaning 'one', referring to a single object or person:
Notice also that we usually say a hundred, a thousand, a million.
When there is no article:
with names of countries (if singular)
with the names of languages
with the names of meals.
with people's names (if singular):
with titles and names:
After the 's possessive case:
with names of shops:
With uncountable nouns:
with the names of individual mountains, lakes and islands:
with most names of towns, streets, stations and airports:
in some fixed expressions, for example:
Dictionaries, thesauruses and grammar checkers
A part of the skill of writing is the use of dictionaries, thesauruses, and grammar checkers. For best results, use them often and in the formal writing setting. This alleviates words in passive voice, repetitive usage, and spelling errors.
A style manual helps writers adhere to evolved rules and conventions. In the U.S., writers use style guides from academic institutions, professional organizations, and corporations. The major style guides, however, are the Associated Press Stylebook and the Chicago Manual of Style (CMS). Generally speaking, journalists use the AP Stylebook and most other writers CMS, unless their work requires the style guide of a particular institution or corporation. The Microsoft Manual of style began as Microsoft's corporate style guide but enjoys wide use by technical writers for computer-specific issues.
Why use a style manual?
A good style manual guides writers through the complex world of English punctuation, syntax, grammar, and other writing issues. In some cases, style manuals disagree on minor points. For example, journalists, who follow the AP Stylebook, do not usually use a terminal comma: "chickens, ducks and geese." Outside journalism, writers who follow CMS use a terminal comma: "chickens, ducks, and geese." Use the convention appropriate for the type of writing, but even more importantly, use the same convention all the way through the document or project. A style manual provides a basis for applying rules and conventions consistently.
back to Technical Writing Level 1