nemo
/
hn-classics
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
hn-classics/_stories/2009/11915309.md

17 KiB
Raw Blame History

Source

The 7 Rules for Writing World Class Technical Documentation - Developer.com

Hot Topics:

prev

next

Developer.com

Techniques

Read More in Techniques »

The 7 Rules for Writing World Class Technical Documentation

Tweet

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.

Page 1 of 2

    • 1
  • 2

IT Solutions Builder TOP IT RESOURCES TO MOVE YOUR BUSINESS FORWARD

Which topic are you interested in?

Mobile

Security

Networks/IoT

Cloud

Data Storage

Applications

Development

IT Management

Other

What is your company size?

                Select company size 1-9 10-24 25-49 50-99 100-249 250-499 500-999 1000+

What is your job title?

                   Select job title C-Level/President Manager VP Staff (Associate/Analyst/etc.) Director

What is your job function?

                   Select job function IT - General IT - Project Management IT - Systems/Network Administration IT - Developer IT - Tester/QA Accounting/Finance/Legal Academic/Research Administrative General Management Human Resources Marketing Operations Sales Consultant Other

Searching our resource database to find your matches...

Please enable Javascript in your browser, before you post the comment! Now Javascript is disabled.

0 Comments (click to add your comment)

Comment and Contribute

 

Your name/nickname

Your email

Subject

(Maximum characters: 1200). You have characters left.

 

 

Enterprise Development Update

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

Most Popular Developer Stories

Most Commented On

Sitemap | Contact Us

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