February 25, 2021
Hot Topics:

The 7 Rules for Writing World Class Technical Documentation

  • By Bob Reselman
  • Send Email »
  • More Articles »

4. Avoid ambiguous pronouns

Ambiguous pronoun references are probably the most typical cause of confusion in the practice of technical writing.

Consider the paragraph in Listing 4.

Listing 4: A paragraph that has ambiguous pronouns

Trafalgabors are a fundamental component of the Weebietatas framework. This article shows you what they are about and how to use them.

This paragraph may seem a bit comical, but it illustrates some important points. First, the paragraph attempts to put you in a place that the reader occupies. The reader wants to understand what's going on but is unfamiliar with the language in play. And because the language is unfamiliar, the reader is ignorant and thus, vulnerable. The reader wants new information; he or she wants to get smarter. But the reader is also a bit anxious. Admitting ignorance, even to one's self, even at a subconscious level, can be disconcerting. The reader is cognitively fragile. Concepts and words that you, the writer, take for granted, might be completely foreign to the reader. One ill explained concept or one word used without proper clarification can turn the reader off.

In the case of the paragraph above, I would not be surprised were you to be asking, "What is a Trafalgabor? What is a Weebietata? What is the paragraph talking about? How to use Trafalgabors? How to use Weebietatas? How to use both of them? This is confusing. I am going back to my Facebook page."

If a reader has to take time out from your writing to figure out what you are trying to communicate, not only is expository flow compromised, the reader most probably will become confused. Once you confuse the reader, you've lost. All the other stuff in the world demanding the reader's attention becomes more attractive than your work. So, the "next" button is clicked and your work goes unread.

In the case of Listing 4 shown above, the confusion is caused by the ambiguous use of the pronoun, they in the second sentence. Does they refer to the Trafalgabors, the Weebietatas or both? Remember please that the reader knows nothing of Trafalgabors or Weebietatas. (Please see Figure 1 below.)

Avoid Ambiguous Pronouns
Click here for larger image

Figure 1: The use of ambiguous pronouns makes technical writing confusing

The solution to the problem is simple. Please take a look at Listing 5 below. The ambiguous pronoun is removed. Clarity is restored.

Listing 5: A remedy for ambiguous pronouuns

Trafalgabors are a fundamental component of the Weebietatas framework. This article shows you what Trafalgabors are about and how to use them

Beware! The ambiguous use of pronouns is a sign post on the road to confusing technical writing.

5. clarity = illustrations + words

Please take a look at the photo below. Tell me if you can, what is the graphic about?

Photo without context

I am not surprised should you find yourself a bit perplexed. It's a perplexing photo. You know what the items are, but you have no idea what they mean. Such is the nature of an illustration. A picture without words lacks context.

When it comes to illustrations, readers require context in order to avoid confusion. The reader should not need to waste time or thought trying to figure out what an illustration is about. The easiest way to avoid confusing illustrations is to provide a caption.

Please take a look at the Figure 2 below. It is the same photo. There is little question as to what the photo is about.

Photo without context
Click here for larger image

Figure 2: The tools and ingredients required to make an Orange Cranberry Tangerine Fizzle

When it comes to technical writing, I have found it to be a good practice to provide numbered, descriptive captions with all illustrations.

Please, don't create captions that are figure numerals only. Use both a figure numerals and a descriptive comment in the caption. Also, you'll do well to avoid orphaning illustrations. An orphan illustration is a figure that exists within the piece of technical writing yet has no reference from within the copy.

If you insert an illustration into your writing, make sure to refer to it in your copy by figure number and location using words such as, above and below. You don't want to reader taking time out from reading your work to try to associate an illustration to copy or to locate an illustration within your article. If you add have a "Figure 4" in your piece, make sure that you have language in the text that says something like, please refer to Figure 4 below.

Note: The eye is attracted to pictures

A decade back I worked in the group that wrote hard copy user manuals for a very, very big computer manufacturer. All manuals were subject to formal, quantitative usability study. One of the things that the User Experience Ph. Ds taught me is that as a subject reads a manual, the reader's eye goes to the pictures first. Then the reader will read the copy around the picture. Thus, the manual writer's tried to make sure that every page of a manual had at least one picture.

6. When dealing with concepts... logical illustration and example, logical illustration and example

Concepts are hard to understand....that's why they're called, concepts. So, when it comes time for me to write about a concept, whether it is, the Second Law of Thermodynamics, a piece of coding technique or a full fledged software framework, I use the following pattern in my writing: concept - logical illustration - example. I try to never introduce a concept without substantiating the concept with a logical illustration and then an example.

Let's apply this rule to describe an elementary algebraic concept.

The Transitive Property of Equality is as follows:

If A = B, and B = C, then A = C

Now let's provide a logical illustration that describes the concept. (Please see Figure 3.)

Transitive Property of Equality
Click here for larger image

Figure 3: Thee Transitive Property of Equality is a fundamental principle of elementary algebra

Listing 6 below shows a few concrete examples to solidify the understanding of the concept at hand.

Listing 6: Some concrete examples of the Transitive Property of Equality

  • If 7 = 3 + 4, and 3 + 4 = 5 + 2, then 7 = 5 + 2
  • If 12 + 5 = 7 + 10, and 7 + 10 = 6 + 11, then 12 + 5 = 6 + 11
  • If x + y = z, and z = 2a, then x + y = 2a

Thus, the rule as has been satisfied. We presented the concept, The Transitive Property of Equality, provided a descriptive illustration and followed up with concrete examples that substantiate the concept.

Let's move on to a concept that is more relevant to software development and a bit more difficult to understand. The concept is Maven POM Inheritance. In Exhibit 1 below you are presented with the concept at hand and then a logical illustration that describes the concept. Finally, you are presented with another illustration that shows the concrete use of a POM files in an inheritance situation.

Exhibit 1: An excerpt of technical writing that describes Maven POM Inheritance

Understanding POM File Inheritance

A POM file (Project Object Model) is the XML file that you use to describe and work with a Maven project. You can set up a Maven project to inherit settings from a separate parent POM file. The ability to inherit settings from a parent POM file is called, POM Inheritance. You use the <parent> element in your POM file to define a parent POM file from which to inherit settings.

Figure 4 below illustrates a fictitious project hierarchy that represents an example of how you can set up a master POM file from which other POM files can inherit common settings.

POM Inheritance
Click here for larger image

Figure 4:You can designate a master POM from which you can inherit common settings

Figure 5 below shows the contents POM.xml files for the Maven projects, stooges-web, stooges-api and stooges-dal. Each project is configured to use the <parent> element to inherit settings from stooges-project.

POM Files in Action
Click here for larger image

Figure 5: Use the <parent> element to direct a Maven project to inherit settings from an external POM file.

The example above relies heavily upon figures to provide logical illustration and a concrete example of the concept at hand. Creating interesting, engaging and accurate illustrations and examples are a difficult undertaking, but well worth the effort. Many times creating the illustrations for a piece of technical writing and providing example code will take as much, if not more time than writing the actual copy. Thus, I plan accordingly when allocating my time to meet a deadline.

When it comes to making a concept crystal clear, illustrate and then provide an example.

7. Embrace revision

It's rare to produce a good piece of technical writing right off the bat. Understanding your topic, organizing your ideas and then finding the language to present the ideas clearly and accurately takes time as well as a lot of effort. Therefore, don't constrain yourself by expecting to get everything right the first time. Rather, plan to write at least three versions of your piece. The first version just gets some words in print so that you can understand your intentions. The second version brings clarity and accuracy to your work. Then, once you have your facts right, your illustrations clear and your organization logical, create a third version that makes your work engaging and special.

To hijack the Thomas Edison quote, "Technical writing is 10% composition and 90% revision!"

Bonus section

Now that you learned about the 7 Rules for Creating World Class Technical Documentation, I am going to share with you the process that I use to create a piece of technical writing. It's short, but to the point. I call the process, The 7 Steps for Making a Technical Document. Here goes:

  1. I create outline, at least to the second level, hopefully to the third.
  2. I add to the outline my illustration for each concept.
  3. I caption my illustrations.
  4. I fill in the copy to the outline, following the Two Sentence Rule, adjusting my outline to adapt to the copy at hand.
  5. I revise.
  6. I send the piece to a subject matter expert for review. (A subject matter expert is a person that can identify inaccuracies and unclear writing.)
  7. I revise again based on the response of the reviewer(s).

There you have it. 7 Rules, 7 Steps. Who could ask for more? So, now that you've learned all of my tricks, feel free to go forth and make the world a more accurate, engaging, illustrative and interesting place in which to live. It's worth the effort.

Page 2 of 2

This article was originally published on November 30, 2009

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date