This booklet is part of Step 3 Presenting of the five-step documentation process (Step 1 – Capturing Information, Step 2 – Structuring Information, Step 3 – Presenting Information, Step 4 –Communicating Information, Step 5 – Storing and Maintaining Information). This booklet provides some basic tips, techniques, approaches and exercises for understanding and practicing effective technical writing.
Documentation Workbook Series. Step 3 Presenting Information (Technical Writing)
SUPERCHARGING YOUR DOCUMENTATION
By Adrienne Bellehumeur
This booklet is part of Step 3 Presenting of the five-step documentation process (Step 1 – Capturing Information,
Step 2 – Structuring Information, Step 3 – Presenting Information, Step 4 –Communicating Information, Step 5 –
Storing and Maintaining Information). This booklet provides some basic tips, techniques, approaches and exercises
for understanding and practicing effective technical writing.
1 | P a g e
Crash Course in Technical Writing
Effective technical writing is key to ensuring that your documentation is
understandable, usable and ultimately adds value.
Once you have understood how to Capture the relevant information
you need (Step 1) and then Structure your documentation (Step 2), it is
time to ensure that your audience understands it. Effective technical
writing is key to ensuring that your documentation is understandable,
usable and ultimately adds value.
Effective documentation shares the same fundamentals as corporate
communications, demanding conscious effort to get the message across
to readers. Unfortunately, most documenters make the common – and
inexcusable – assumption that no one is actually going to read their
document. Why bother documenting if no one is going to read
it anyway? Don’t you have something better to do?
The Two Key Concepts of Technical
Writing: Clarity + Engagement
You have probably been out of school for some time and are therefore
caught up in the grind of work. With so many documents and emails being exchanged, it is easy
to become complacent about your writing skills.
There are many rules of grammar which this
booklet does not cover; you are recommended
to consult another source if you are interested in
brushing up. This booklet does, however,
emphasize the two most important concepts
when it comes to improving your technical
writing: (1) Clarity and (2) Engagement.
Being a good writer is critical
to your career success.
2 | P a g e
CLEAR CONCEPTS FOR EFFECTIVE WRITING
Your reader must be able to
understand your document easily
and immediately. Make every word
and visual aid have a function, and
leave out unnecessary elaboration.
Business writing is practical – you
aren’t writing poetry or a thriller
Your reader must want to read your
document. Writing must be
engaging in order to be successful.
You need to convey conviction in
order to drive momentum: you are
speaking from the voice of the
Get to the Point — Quickly
You want the reader to understand your topic as quickly as possible. You must have the
reader’s end goal in mind at all times.
Simplify Your Language
Make your text short and snappy by simplifying your grammar and vocabulary. Shorten
sentences by cutting out as much punctuation as you can without affecting the
readability of the sentence. Use fewer commas, more periods, and no semicolons at all,
Structure the Document
When structuring your article, its sub-sections, and each sentence, imagine an inverted
pyramid — put all the important information at the top, followed by supporting details.
Always put the most important information in the main clause of each sentence. This
technique helps a reader quickly find the information he or she needs.
3 | P a g e
For Improving Technical Writing
Use these quick tips for effective results:
(1) Cut Down Your Use of the Passive Voice
The passive voice is a plague on effective documentation. It reduces its clarity,
consistency, and the efficiency and tightness of the writing. The passive voice is writing
in which the subject of the sentence denotes the recipient of the action rather than the
performer. For example, “the server was installed” represents the passive voice while
“the technician installed the server” represents the active voice. The passive voice is
also an easier, sloppier way of writing – so, it is very easy to fall into the trap of using it
3instances when you need to use the passive voice in your writing:
(1) When the actor is unknown or irrelevant
(2) When you are talking about a general truth or
(3) When you want to emphasize the person or thing acted on
Excessive Use of the Passive Voice is
detrimental to documentation, especially to
process-related documents where it is
essential to understand which people or
systems are performing the actions. The
good news is that this is easy to fix. Under
your Grammar function in Microsoft Word,
you can click on the “Passive Sentences”
option and Word will automatically check for
passive sentences for you.
Do not use:
“The server was installed.”
“The Technician installed
4 | P a g e
(2) Use Punchy Titles, Bullets and Key Points
Your audience wants to exert as little energy as possible when reading your work.
They’ll just “skim” your document looking for the key points. So, make things easy for
them. Headers, bullets and key points, often combined with effective visuals, are as
important as the text. Some readers only read headers and bullets, and might even
make a decision about your work based on reading only the Table of Contents. When
assessing your document, it’s helpful to communicate the entire gist of your work within
the headers, bullets and key points alone. Be sure to bold or highlight the key messages
in your document so that your reader doesn’t have to go looking for them.
Test out this technique with a co-worker. Can your reader understand your key
messages through the headers, bullets, table of contents, and the bolded points
alone? If they can understand most of what you are saying, then you have succeeded in
making your document clear and easy to read. If not, invent more descriptive titles and
bolded points and then try the test again.
Do not use the Heading:
Do use the Heading:
“Review of Critical Financial Interfaces: Results & Conclusions.”
(3) Tame Your Acronyms and Buzz Words
There is nothing more confusing than walking onto a project or into a new organization
and being unable to understand a document because it is full of acronyms and buzz
words. Acronyms and buzz words do not make you sound smarter. In most cases, they
actually annoy your reader by hindering his or her ability to grasp your key messages.
Avoid using them or define them upfront. In many cases, you should define acronyms
and frequently used words in a thorough Glossary at the beginning of your document or
as part of your documentation library.
5 | P a g e
Do not use:
“The CSR gives all CCF’s to the TL at the end of the day.”
“The Customer Service Representative (CSR) gives all customer
complaint Forms (CCF’s) to the Team lead at the end of the day.”
(4) Remove Deadwood
Any word or phrase that does not add value will lessen the impact of your
documentation. Take it out.
Look out for excessive use of these words…
o At this point in time
o due to the fact that
o that is
o as well as
o and so
(5) Use Clear Wording
Be careful with the words you choose. Use plain, concise wording and steer clear of
verbose language. Here are commonly used words that have simpler alternatives.
Consolidate with Combine
Pursue with Follow
Utilize with Use
Endeavor with Try
Commence with Start
Peruse with Check
6 | P a g e
Look Out for the Passive Voice
Get a partner, preferably a co-worker, who is also
interested in improving his or her Technical Writing skills.
Now that you have learned to watch out for excessive use of the passive voice, let’s see how
much you are using it in your current writing. You can do this exercise on your own or working
with a partner (or co-worker).
This exercise will help you to understand how you are currently using the passive voice. It will
also give insight into how to improve your use of both passive and active voices.
(1) Pick a document that you are working on.
(2) Turn on the “Passive Sentences” function in Microsoft Word.
(3) Count how many times that you used the passive voice.
(4) With your partner, discuss your results.
Where should you be using the active voice instead of the passive voice?
Where is your use of the passive voice appropriate?
(5) Create a new separate document and rewrite the original document to change your passive
sentences into the active voice where appropriate.
(6) Read the original document and the revised documents out loud to your partner.
7 | P a g e
THINGS TO CONSIDER…
Which document is clearer to understand?
Where did the active voice improve the clarity of your document?
Where was it difficult to get rid of the passive voice? Explain Why?
Where was the use of the passive voice appropriate or necessary?
8 | P a g e
Writing Tip – THE 7±2 Rule
The human mind can remember 7±2 related items in short-term memory at one time. This is
also why there are seven dwarfs, nine members of the Brady Bunch, and "seven strangers" on
MTV's The Real World.
When you put together a procedure, try to limit it to a maximum of seven or nine steps. If you
have a very long procedure, break it into tasks. Each task has a maximum of seven or nine
ADDITIONAL ONLINE RESOURCES: