SUPERCHARGING YOUR DOCUMENTATION

1

TECHNICAL WRITING

By Adrienne Bellehumeur

www.leadersinbusinessanalysis.com

This booklet covers Step 3 Technical Writing of the six-step documentation process (Step 1 – Capturing, Step 2 –

Structuring, Step 3 – Presenting, Step 4 – Visual Documentation, Step 5 – Documentation for Effective Meetings,

Step 6 – Storing & Maintaining Information). This booklet provides some basic tips, techniques, approaches and

exercises for understanding and practicing how to capture information effectively.

WORKBOOK SERIES

3

1 | P a g e

CHALLENGE

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.

PERSONAL INSIGHT

Being a good writer is critical

to your career success.

2 | P a g e

CLEAR CONCEPTS FOR EFFECTIVE WRITING

Clarity: 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

novel.

+

Engagement: 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

expert.

KEY POINTS

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,

if possible.

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

QUICK TIPS:

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

too much.

3 instances 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.”

Do use:

“The Technician installed

the server.”

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:

“Interface Conclusions”

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.”

Do use:

“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 however

o due to the fact that

o that is

o moreover

o as well as

o furthermore

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.

Replace:

Consolidate with Combine

Pursue with Follow

Utilize with Use

Endeavor with Try

Commence with Start

Peruse with Check

6 | P a g e

EXERCISE:

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.

STEPS: (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

steps.

ADDITIONAL ONLINE RESOURCES: Technical Writing

http://idratherbewriting.com/

http://www.plainenglish.co.uk/

http://www.bartleby.com/141/

http://www.sensei.ie/communication/8-essential-online-resources-for-technical-writers/

https://technicalwritingtoolbox.com/technical-writing-resource/

http://www.writing.utoronto.ca/advice/general/essay-topics