This guest blog post was written by Delio Destro. Delio is the founder and director of Flexwrite Technical Documents in British Columbia, Canada.

“Easy reading is damn hard writing.” Nathaniel Hawthorne

What is technical communication? I have been asked this question many times over the years. The answer can be as straightforward or complex as we choose to make it, but this is how I see it.

I like to start by defining what it is not:

  • It is not an art form.
  • It is not a platform to express yourself.
  • It is not a vehicle to show off how much your company knows about its products.
  • It is not a marketing or sales tool.

I rather settle for the straightforward version:

Technical communication conveys focused, sufficient, and correct information about a specific subject to a defined audience. ONLY!

  • Focused: It describes only the subject at hand—nothing else.
  • Sufficient: It must contain all information necessary to complete the task, relying very little upon or not at all on external references.
  • Correct: All the content must be verified. Always, always, always, have it reviewed by more than one subject matter expert (SME). If in doubt, don’t publish it.

Who Do We Write For

Like many people in this profession, I came to it through the back door. I started my career in the early 80s as a field service engineer for a rep company (A rep company is a representative office of a principal in a territory. It acts as an office for that company in the territory without actually being a part of it.) in Brazil. I marveled at those 500-page operation and maintenance manuals that I proudly carried to my customers’ sites. They had everything: drawings, pictures, component sizes and shapes, and detailed descriptions on how the machine worked, down to the signals and pulses. Everything!

Or so I thought.

One day, while repairing a component inserter, I was looking for information on how to take apart its placement head. I realized I could build another machine with what was in the user manual but could not find simple instructions on how to repair it. Suddenly, the entire user manual was useless to me.

It was then when it hit me: the engineers who wrote that manual were brilliant, but they had never serviced the machine in the field. They documented what they knew about the technical specifications; they never considered what I needed.

Fast forward to 1994 when Brazil enacted a law requiring that all imported equipment must have operations, service, and installation instructions in Portuguese. I started translating the manuals and, in the process, shedding what was not needed in the field, and adding what my field service engineers wanted to see. They loved it.

My customers liked it too and started asking me to review their other manuals. I started to invest more time into it, reading a lot of good books, and it eventually became the business that I’ve been running ever since.

When I moved to Canada, I went back to school for a proper education in the field, but the basic lesson I had already learned long ago: “write technical documents to solve somebody else’s problems, not yours”. Keep reading to discover more on how to write technical documentation for your intended audience.

The Top 5 Ways to Create Effective Technical Documents

1.The Four Questions

Before creating a technical document, ask these four key questions:

WHO?

Who is your audience? Who needs this document?

It is an important question in creating any document but essential when creating technical documentation.

The document must provide the information that your audience needs and understands.

The Who profile refers not only to the technical knowledge of your audience but other factors such as physical limitations. For instance, if the group using the information is mostly over 40 years old, you may want to use larger fonts in your style guide and be more generous with white space.

I can’t stress this enough: If you don’t answer the Who clearly, don’t even bother asking the other questions.

WHAT?

What are you going to talk about?

You don’t have to master the subject you are writing about as your SME does, but it helps to have an overall understanding of the subject and the associated technologies. Read about the subject and take your SME feedback into consideration before committing words and pictures to paper.

Also, focus on the action. If the document’s goal is to describe “how to launch a rocket” don’t talk about the rocket’s fuel system or the launch platform layout. Focus on creating product documentation that speaks to when and how to use the Ignition Key, Launch Button, Abort Button, and what to do in an emergency. Only.

WHEN?

When is the document required?

This is a more subtle factor, but it may significantly affect how much and what type of content you make available. If it is a production line or emergency publication, favor clear, large, and colorful symbols over detailed descriptions.

WHERE?

Where is this document physically used?

Consider where the document is employed most frequently. Ambient light, noise, and level of cleanliness may severely affect what goes into a technical document and the best publishing format.

For example: laminated printed pages work a lot better than e-Books in a car garage.

2. Keep it Simple

When it comes to document design in technical writing, consider how to outline and organize what is needed as directly as possible. Simple and direct bullet points are much more likely to be read and executed correctly than long descriptive instructions.

This is a text from an actual operation manual:

At the end of a shift or, if the plant is to sit idle for a prolonged period, it is recommended that a wash cycle (water only) be run for a more thorough cleaning. Multiple wash cycles are recommended until discharged water runs clean. Following the wash cycles, the doors at the base of the mixer, the main mixer door, and the top mixer hatch should all be fully opened. The mixer interior must be inspected for cleanliness and if not fully clean the mixer interior should be manually cleaned as required. The top and bottom of all feed valves should also be cleaned. Doors should be left open between shifts to ensure the following shift starts with a clean mixer.

This is what the end-user actually needs:

At shift’s end or before an idle period (> 2 days):

  1. Run wash cycles (water only), until the discharge is clean;
  2. Fully open all doors and hatches;
  3. Inspect for cleanliness. If not fully clean, clean manually;
  4. Clean all feed valves;
  5. Leave doors open.

One good rule to live by when writing technical content and procedures: One action, one sentence.

3. Use Simple Words

Keeping the text simple is good. Period.

Instead of:

Use:

Perform

Do

Utilize

Use

Prior to

Before

Retain

Keep

The United States Government maintains a website dedicated to keeping documents simple and easy to read. Visit www.plainlanguage.gov.

4. Use Direct and Blunt Speech

Don’t try to sound polite by using indirect speech, conditionals, or colorful remarks.

Instead of

“Step #2:

“At this point, the bolt should be carefully removed”

Use:

“Step #2:

“Remove the bolt”

-

-

(Nobody removes a bolt carelessly, just because…)

5. Illustrate with a Purpose

DO NOT use illustrations for:

  • showing how beautiful or big the machine is;
  • making it look like the subject is very complicated; hence this is a good document;
  • showing off your CAD software capabilities;
  • proving that you are not color blind.

Use illustrations for:

  • Minimizing or eliminating the need for words. ONLY.

Recommended Books on Technical Communication

There are great books about technical communication. Whether you are starting in this field or if you are a seasoned writer, these are the three references I recommend that also include great technical documentation examples:

The Elements of Technical Writing

by Gary Blake and Robert W. Bly (MacMillan-USA)

It is short, to the point, and has no mumbo-jumbo whatsoever. Sounds familiar?

Developing Quality Technical Information - A Handbook for Writers and Editors

By Gretchen Hargis et al. (IBM Press)

This book, written by several authors, presents a very diverse perspective of different areas of technical communication. Moreover, it covers areas other publications overlook, such as software documentation.

Visual Language for Designers - Principles for Creating Graphics that People Understand.

By Connie Malamed (Rockport Publishers)

This book is not about technical illustration. It is about how the brain reacts and processes visual stimulation. It is surprising how technical documents can improve when the author internalizes some key visual concepts.

Invest in Training Programs

Can you become a technical communicator without proper schooling? Yes, you can. I did it. However, I don’t recommend it.

Most universities and technology institutes have excellent programs in this field, and I strongly recommend starting in this profession by completing a program at a higher education level.

In British Columbia, the BC Institute of Technology and Simon Fraser University have excellent online programs in technical communications.

Also very important: learn your language well. Invest in training programs and tutors to write correctly. And buy good training manual software too.

Wrap Up

In the end, our job as technical communicators is to convey the ideas between groups of people who, in most cases, have entirely different backgrounds and needs.

Going philosophical here: Language is the human way of transforming an idea into sounds or signs so that the same idea materializes in the other persons’ brain when the sounds or signs reach them. Say it wrong, and the idea may not form quite as you want it.

This may be very important when replacing an aircraft engine.