Sealyu

Introduction

Writing a technical document is hard. Reading a poorly written technical document is harder, and probably more painful than writing one. It takes a lot of work to create a clear, accurate, engaging piece of technical writing. Thus, in order to make life a little easier for all parties involved, I am going to share with you the 7 Rules that I follow when creating a piece of technical documentation. I did not think these rules up on my own. Rather, I formulated them from having had the benefit of working with many gifted technical and copy editors for more than a decade. Anything that I understand is because others have shown me the way. I cannot be more grateful.

Hopefully after reading this article, you will have some new tools in your technical writing toolbox that will help you create technical documents that are clearer, more engaging, less confusing and a lot more fun to read. Also, I've added at no extra charge to you, the consumer, a bonus section at the end that describes the process I use to create a piece of technical writing.

Okay, so here are the 7 Rules:

1. Dry sucks
2. Before you start, be clear about what you want your reader to do after you end
3. Write to a well formed outline, always
4. Avoid ambiguous pronouns
5. clarity = illustrations + words
6. When dealing with concepts... logical illustration and example
7. Embrace revision

1. Dry sucks

This is probably the hardest rule to formalize and the most important rule to follow. In the modern world of the Internet there are many forces at work vying for the attention of your reader. Boring, business as usual writing will not work. For better or worse, your reader wants to be entertained as well as informed. Therefore, if you create writing that is unclear and not fun, the reader will simply click the proverbial "next"; button and move on to another web page, another TV show or his or her Facebook page.

The easiest way that I've found to keep the reader entertained is to keep myself entertained. I make a significant effort always to write an article that I will want to read. I strive to have fun when I am writing. If I'm bored, the reader will be bored. If I'm confused, the reader will be confused. If I don't really care about the topic at hand, the reader will never care. It's that simple.

I like humor, so I try to make my writing humorous without compromising clarity. I try to talk to the reader, not at the reader. I write about topics that really matter to me. I use illustrations extensively in order to avoid confusing the reader.

Again, I try always to make the reading experience fun. I am aware always that I am writing in a competitive environment. There's a lot of content out there that wants a piece of the reader's attention. Thus, my advice for Rule #1 is, if you make your writing fun for you, it will be fun for the reader.

2. Before you start, be clear about what you want your reader to do after you end

Technical writing is all about the subsequent behavior of the reader. The reader is investing time reading your work because he or she wants to be able to do something after the reading experience is over. That something may be learning how to make chocolate chip cookies, power down a nuclear reactor or set up a Hadoop cluster. The important thing to remember is that the reader is using your writing as a means to another end. Your piece is a vehicle to another well defined behavior.

Thus, it will do you well to be very clear about what you want your reader to do after the reading experience is over. State your intention at the beginning. Don't leave the reader guessing. Your declaration can be something as simple and obvious as, "after reading this article you will be able to [fill in the blank here]." If you are clear about what you want your reader to do after you end, the easier it will be for you to write your piece at the beginning.

3. Write to a well formed outline, always

A well formed outline is the skeleton around which your document grows. Writing a technical document without using an outline is like trying to navigate the New York City Subway System without a map. You can end up anywhere and that anywhere may not be where you intended to go.

Writing to an outline is not about creating more work. It's about doing less work. When you write to an outline, you know where you've come from and where you are going to.

There are two rules of outlining that I always use.

1. A sublevel topic requires at least one peer.
2. Any outline level requires at least two sentences.

Allow me to elaborate. Listing 1 below is an example of an outline that violates the first rule: A sublevel topic requires at least one peer.

Listing 1: A poorly formed outline

1. Making an Orange Cranberry Tangerine Fizzle

1.1. The steps required for the Fizzle

1.1.1. Preparing the ingredients

1.1.2. Mixing the Fizzle

1.1.3. Serving the Fizzle

Notice please that in Listing 1, Level 1, has a single sublevel, 1.1 - The steps required for the Fizzle. This structure is a violation of the first rule. In order for a sublevel to be well formed, there must be at least one other peer for a topic. In other words, this means that there must be at least two sublevels for any given level.

Please look at Listing 2 below. Notice that there are now three sublevels to Level 1, of which the topic, Mixing the fizzle, now has peers. The single level, The steps required for the Fizzle, has been eliminated.

You may ask, "Where is the topic, The steps required for the fizzle?" The answer is that the topic is no longer an outline item but content within the parent topic as shown in Listing 2 below.

Listing 2: A well formed outline that violates the two sentence rule

1. Making an Orange Cranberry Tangerine Fizzle

The section below describes the process that you need follow to make an orange cranberry tangerine fizzle.

1.1. Preparing the ingredients

1.2. Mixing the Fizzle

1.3. Serving the fizzle

Please notice that although Listing 2 presents an outline with a properly structured sublevel, there is only a single sentence as content for the Level 1 topic. Having a single sentence only as content to an outline topic violates the second rule of outlining, Any outline level requires at least two sentences.

Listing 3 below shows the Orange Cranberry Tangerine Fizzle piece adjusted to support the Two Sentence rule.

Listing 3: A well formed outline that supports the Two Sentence Rule

1.Making an Orange Cranberry Tangerine Fizzle

An Orange Cranberry Tangerine Fizzle can be a welcome treat on a hot summer day. The beverage is made from natural ingredients with no artificial flavors. An Orange Cranberry Tangerine Fizzle not only tastes good, but it’s good for you too!

The sections below describe the process that you need follow to make an Orange Cranberry Tangerine fizzle.

1.1. Preparing the ingredients

1.2. Mixing the Fizzle

1.3. Serving the fizzle

Why all the hubbub about proper outline structure and at least two sentences to a level? First, following the Sublevel rule forces me to be very clear about the logical segmentation of my piece. Also the Sublevel rule ensures that my writing communicates my ideas with a flow that makes sense and is easy to follow.

Second, The Two Sentence rule forces me to create copy that is engaging, detailed and makes sense. "One sentence" writing often lacks detail. And, with the exception of one- liner comedy, writing of the "one sentence" variety is not the most interesting copy to read.

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.

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

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.

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?

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.

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.

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

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

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.