Table of Contents
Chapter 1: Technical Writing
Attributes of Technical Writing
- clear: no possibility of misinterpretation or ambiguity. Understood the first time.
- complete: provides all needed information for understanding and to facilitate followup
- concise: clear and complete, but as brief as possible
- accessible: organized and tagged: headings, bullets and the like. readers should be able to find the needed information without reading the entire document
- accurate: the document must not contain factual errors.
- correctness: must be free of grammatical and mechanical errors. [from lecture]
To achieve these goals, always consider two things:
- the purpose of the document
- Are you trying to inform readers? Get them to do something? Both?
- the intended reader
- Does the reader need you to provide context? Define terms? Is the request an easy ask or a hard ask?
- Ask yourself: what does the reader need to know so that they understand what you’re saying and will agree to what you’re asking?
The Reader
It may be helpful to group readers into several broad categories:
Decision Makers: Usually somewhat detached from the technical details of a project, even if they have the background to understand them. Receives a large volume of correspondence and so appreciates brevity. Understanding likely outcomes is essential for them. Because they are decision-makers, understanding their information needs is critical.
Experts: Understands and engages with technical information, and often requires in-depth context. Has an important, if indirect, influence on decision making.
Agents: The readers who carry out instructions outlined by the document. Clear, organized instructions that enable to effectively carry out their job without your technical expertise are essential. Explanation of why changes are necessary and how they will improve their workday helps maintain morale.
General Readers: People with the least amount of technical information, typically outside of your organization. Technical terms need to be defined using simple, quick to understand methods, such as simple graphs and illustrations. They also appreciate understanding how the changes in the document will benefit them.
Putting it together
Brainstorm the Content
With the reader in mind, jot down all the information that may be relevant and useful.
Organize the Content
Rather than rewriting, you could draw lines between ideas, number them, moving them around in the text editor, etc. Consider the most logical flow of information. You can imagine the document as a one-way conversation with your reader, or as a story told to your reader.
-
Begin a document with a summary, ie “why are you talking to me?”. In longer documents, it is often a good idea to write this last (but still at the beginning of the document) so that you know what you are summarizing. The summary in this case can be thought of a separate much shorter version of the rest of the document.
-
Next, provide additional context that reinforces why the reader is receiving the document.
-
Provide all necessary details to understand exactly what you are trying to communicate or request.
-
End with whatever next step is required to followup. If none, offering to answer questions or continue the conversation works.
Determine the Correct Writing Style
Based on the audience type, consider the correct writing style for the document
Write the First Draft (without stopping)
Just get it down. This can be rough, dont stop to edit or think. Its useful to have a starting place. Imagine it as simply speaking directly to your reader. (maybe this is a good place for AI to step in if its part of the workflow)
Revise in Stages
Revisions should work from broad to granular.
- Substantive Editing: Edit for content and sequence. Too much? Too little? Wrong order?
- Stylistic Editing: Edit for style and tone. Does it sound good and tonally correct when read aloud?
- Copy Editing: Grammar and mechanics. Double check citations, references, etc. If necessary, add supporting documents such as glossaries. Double check the spelling of names, correctness of phone numbers, etc.
- Proofreading: Apply the content to the final page layout template. Then check for mislabeled heading, misaligned paragraphs, misplaced figures, etc. Check for any typos and other mistakes missed in Copy Editing. A second pair of eyes is helpful here.
Chapter 2: Technical Sentences
A good technical sentence should be clear, direct, simple and effective.
When in the stylistic editing revision stage, edit your sentences with the following six steps.
- Find the real subject
- Find the real verb
- Edit for conciseness
- Edit for clarity
- Edit for inclusive language
- Check the grammar and mechanics
1. Find the Real Subject
The word “subject” has two meanings:
- grammatical: the thing in the sentence that makes the verb happen.
- topical: what the sentence is about.
Sentences work better when the grammatical and topical subjects are the same.
It is always best if the subject is as concrete (easy to visualize) as possible.
Be Direct
Sentences work better when the subject appears as close to the beginning of the sentence as possible.
Avoid leading sentences with abstract nouns. For example:
The decision of the engineers was to double the chlorine concentration in the water treatment process.
is a weaker sentence than:
The engineers decided to double the chlorine concentration in the water treatment process.
Because 'the decision' is abstract, and is not the subject of the sentence. Leading with 'the engineers' is more direct and begins with something concrete.
Avoid Weak Expletives
Avoid meaningless sentence starts such as "there are" and "it is". These are called weak expletives. They take the place of the main noun/verb. For example:
There are eight hoisting points that need to be reinforced.
is a weaker sentence than:
Eight hoisting points need to be reinforced.
Sometimes weak expletives are appropriate. For example:
There are times when it is best to begin with a weak expletive.
versus the weaker:
Times exist at which it is best to begin with a weak expletive.
If a sentence is weakened by removing weak expletives, put them back.
Use the Active Voice
In the active voice, the subject should come first in the sentence, and perform the verb on the verb.
To use the active voice in a sentence with two nouns, lead with the actor, not the thing being acted upon.
For example:
The engineer carefully calibrated the instrument.
is a weaker sentence than:
The instrument was carefully calibrated by the engineer.
Some possible exceptions, where you may want to use the passive voice are:
- When you are talking about something that is being acted upon (or in other words, something passive). For example, the passive sentence from the example might be preferable in a larger document about the instrument.
- When the agent is irrelevant, unknown, or intentionally being obscured ("Mistakes were made … Papers were shredded … Relevant emails were deleted")
Address Readers Directly
Get over your fear of using the word ‘you’ in technical writing.
If a leak is detected …
is a weaker start than:
If you detect a leak …
Don’t refer to “one”; use “you.”
One must read all safety rules and instructions before beginning work.
is a weaker sentence than:
Read all safety rules and instructions before you begin work.
Use the Imperative Voice
When appropriate, don’t shy away from a commanding, or ‘imperative’ voice.
No tie-ins should be performed during summer months.
reads more passively than