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

451 lines
18 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
created_at: '2016-06-16T11:01:12.000Z'
title: Rules for Writing Technical Documentation (2009)
url: http://www.developer.com/tech/article.php/3848981/The-7-Rules-for-Writing-World-Class-Technical-Documentation.htm
author: Tomte
points: 74
story_text:
comment_text:
num_comments: 7
story_id:
story_title:
story_url:
parent_id:
created_at_i: 1466074872
_tags:
- story
- author_Tomte
- story_11915309
objectID: '11915309'
year: 2009
---
[Source](https://www.developer.com/tech/article.php/3848981/The-7-Rules-for-Writing-World-Class-Technical-Documentation.htm "Permalink to The 7 Rules for Writing World Class Technical Documentation - Developer.com")
# The 7 Rules for Writing World Class Technical Documentation - Developer.com
![][2]
![][3]
* [Java][4]
* [Microsoft & .NET][5]
* [Mobile][6]
* [Android][7]
* [Open Source][8]
* [Cloud][9]
* [Database][10]
* [Architecture][11]
* [Other][12]
* [Project Management][13]
* [PHP][14]
* [Perl][15]
* [Ruby][16]
* [Services][17]
* [Other Languages][12]
* [White papers][18]
* [Research Center][19]
* [NEW: Slideshows][20]
* [ Sponsored][21]
* * * * February 23, 2018
Hot Topics:
[prev][22]
* [Android ][23]
* [Java][4]
* [PHP][24]
* [Microsoft & .NET][5]
* [Cloud][9]
* [Open Source][8]
* [Database][10]
[next][22]
[Developer.com][25]
[Techniques][26]
[Read More in Techniques »][27]
# The 7 Rules for Writing World Class Technical Documentation
* November 30, 2009
* By [Bob Reselman][28]
* [Send Email »][29]
* [More Articles »][28]
[Tweet][30]
## 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
* [Post a comment][31]
* [Email Article][32]
* [Print Article][33]
* [Share Articles][22]
* [ Digg][34]
* [ del.icio.us][34]
* [ Slashdot][34]
* [ DZone][34]
* [ Reddit][34]
* [ StumbleUpon][34]
* [ Facebook][34]
* [ FriendFeed][34]
* [ Furl][34]
* [ Newsvine][34]
* [ Google][34]
* [ LinkedIn][34]
* [ MySpace][34]
* [ Technorati][34]
* [ Twitter][34]
* [ YahooBuzz][34]
## 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][35], power down a [nuclear reactor][36] or set up a [Hadoop cluster][37]. 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][38] 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][39]
* [2][40]
* * ![][41]
IT Solutions Builder TOP IT RESOURCES TO MOVE YOUR BUSINESS FORWARD
### Which topic are you interested in?
![][42]
Mobile
![][43]
Security
![][44]
Networks/IoT
![][45]
Cloud
![][46]
Data Storage
![][47]
Applications
![][48]
Development
![][49]
IT Management
![][50]
Other
### What is your company size?
![][51]
                Select company size 1-9 10-24 25-49 50-99 100-249 250-499 500-999 1000+
![][52]
### What is your job title?
![][53]
                   Select job title C-Level/President Manager VP Staff (Associate/Analyst/etc.) Director
![][54]
### What is your job function?
![][55]
                   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
![][56]
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)][31]
![][57]Comment and Contribute
 
Your name/nickname
Your email
Subject
(Maximum characters: 1200). You have characters left.
 ![][58]
 
## Enterprise Development Update
Don't miss an article. Subscribe to our newsletter below.
## Most Popular Developer Stories
* [Today][59]
* [This Week][60]
* [All-Time][61]
* [1 Using JDBC with MySQL, Getting Started][62]
* [2 Creating Use Case Diagrams][63]
* [3 An Introduction to Java Annotations][64]
* [4 Hibernate Basics][65]
* [5 Using ASP.NET To Send Email][66]
* [1 Using JDBC with MySQL, Getting Started][62]
* [2 10 Experimental PHP Projects Pushing the Envelope][67]
* [3 Hibernate Basics][65]
* [4 An Introduction to Java Annotations][64]
* [5 Oracle Programming with PL/SQL Collections][68]
* [1 Using JDBC with MySQL, Getting Started][62]
* [2 Hibernate Basics][65]
* [3 Oracle Programming with PL/SQL Collections][68]
* [4 An Introduction to Java Annotations][64]
* [5 Creating Use Case Diagrams][63]
## Most Commented On
* [This Week][69]
* [This Month][70]
* [All-Time][71]
* [1 10 Experimental PHP Projects Pushing the
      Envelope][72]
* [2 Day 1: Learning the Basics of PL/SQL][73]
* [3 C# Tip: Placing Your C# Application in the
      System Tray][74]
* [4 Logical Versus Physical Database Modeling][75]
* [5 Is Ubuntu Contributing as Much as It Should to
      Free Software Projects?][76]
* [1 Day 1: Learning the Basics of PL/SQL][73]
* [2 The 5 Developer Certifications You'll Wish You
      Had in 2015][77]
* [3 10 Experimental PHP Projects Pushing the
      Envelope][72]
* [4 An Introduction to Struts][78]
* [5 Inside Facebook's Open Source Infrastructure][79]
* [1 Creating Use Case Diagrams][80]
* [2 Day 1: Learning the Basics of PL/SQL][73]
* [3 C# Tip: Placing Your C# Application in the
      System Tray][74]
* [4 Using ASP.NET To Send Email][81]
* [5 Using JDBC with MySQL, Getting Started][82]
[Sitemap][83] | [Contact Us][84]
Thanks for your registration, follow us on our social networks to keep up-to-date
[1]: //www.qsstats.com/dcs38irdn10000g0vc4171yva_9y7z/njs.gif?dcsuri=/index.php/tech/article.php/3848981/The-7-Rules-for-Writing-World-Class-Technical-Documentation.htm&WT.js=No&WT.tv=10.4.1&dcssip=www.developer.com&WT.qs_dlk=WpAocQrIZ6wAAAVLTykAAAAG&
[2]: http://b.scorecardresearch.com/p?c1=2&c2=17199065&cv=2.0&cj=1
[3]: https://www.developer.com/images0/developer_oldcolor.gif
[4]: https://www.developer.com/java/
[5]: https://www.developer.com/net/
[6]: https://www.developer.com/ws/
[7]: https://www.developer.com/ws/android/
[8]: https://www.developer.com/open/
[9]: https://www.developer.com/cloud/
[10]: https://www.developer.com/db/
[11]: https://www.developer.com/design/
[12]: https://www.developer.com/lang/
[13]: https://www.developer.com/mgmt/
[14]: https://www.developer.com/lang/php/
[15]: https://www.developer.com/lang/perl/
[16]: https://www.developer.com/lang/rubyrails
[17]: https://www.developer.com/services/
[18]: https://www.developer.com/white_papers/
[19]: https://www.developer.com/research
[20]: https://www.developer.com/slideshows/
[21]: https://www.developer.com/SponsoredHub.php?prx_adpz=1387
[22]: https://www.developer.com#
[23]: https://www.developer.com/ws/android
[24]: https://www.developer.com/lang/php
[25]: https://www.developer.com/
[26]: https://www.developer.com/tech
[27]: https://www.developer.com/tech/archives
[28]: https://www.developer.com/author/Bob-Reselman-91220.htm
[29]: https://www.developer.com/feedback/article.php/3848981
[30]: https://twitter.com/share
[31]: https://www.developer.com#comment_form
[32]: https://www.developer.com/email.php/3848981
[33]: https://www.developer.com/print/article.php/3848981
[34]: javascript:void(0)
[35]: http://allrecipes.com/recipe/best-chocolate-chip-cookies/Detail.aspx
[36]: http://www.howstuffworks.com/nuclear-power.htm/printable
[37]: http://developer.yahoo.com/hadoop/tutorial/module7.html
[38]: http://www.mta.info/nyct/maps/submap.htm
[39]: javascript:void(0);
[40]: https://www.developer.com/tech/article.php/10923_3848981_2/The-7-Rules-for-Writing-World-Class-Technical-Documentation.htm
[41]: https://www.developer.com/images0/arrow_right.jpg
[42]: https://www.developer.com/hqb2b/img/searchwidget/icon-mobile.png
[43]: https://www.developer.com/hqb2b/img/searchwidget/icon-security.png
[44]: https://www.developer.com/hqb2b/img/searchwidget/icon-networks.png
[45]: https://www.developer.com/hqb2b/img/searchwidget/icon-cloud.png
[46]: https://www.developer.com/hqb2b/img/searchwidget/icon-datastorage.png
[47]: https://www.developer.com/hqb2b/img/searchwidget/icon-apps.png
[48]: https://www.developer.com/hqb2b/img/searchwidget/icon-dev.png
[49]: https://www.developer.com/hqb2b/img/searchwidget/icon-itmgmt.png
[50]: https://www.developer.com/hqb2b/img/searchwidget/icon-other.png
[51]: https://www.developer.com/hqb2b/img/searchwidget/article-Q2.png
[52]: https://www.developer.com/hqb2b/img/searchwidget/tracker-2.png
[53]: https://www.developer.com/hqb2b/img/searchwidget/article-Q3.png
[54]: https://www.developer.com/hqb2b/img/searchwidget/tracker-3.png
[55]: https://www.developer.com/hqb2b/img/searchwidget/article-Q4.png
[56]: https://www.developer.com/hqb2b/img/searchwidget/tracker-4.png
[57]: https://assets.devx.com/Icon/icon_comment.png
[58]: https://www.developer.com/images0/ajax-loader.gif
[59]: https://www.developer.com#mostPopularToday
[60]: https://www.developer.com#mostPopularThisWeek
[61]: https://www.developer.com#mostPopularAllTime
[62]: http://www.developer.com/java/data/article.php/3417381/Using-JDBC-with-MySQL-Getting-Started.htm
[63]: http://www.developer.com/design/article.php/2109801/Creating-Use-Case-Diagrams.htm
[64]: http://www.developer.com/java/other/article.php/3556176/An-Introduction-to-Java-Annotations.htm
[65]: http://www.developer.com/java/other/article.php/3559931/Hibernate-Basics.htm
[66]: http://www.developer.com/net/asp/article.php/3096831/Using-ASPNET-To-Send-Email.htm
[67]: http://www.developer.com/lang/php/article.php/3896056/10-Experimental-PHP-Projects-Pushing-the-Envelope.htm
[68]: http://www.developer.com/db/article.php/3379271/Oracle-Programming-with-PLSQL-Collections.htm
[69]: https://www.developer.com#mostCommentedOnThisWeek
[70]: https://www.developer.com#mostCommentedOnThisMonth
[71]: https://www.developer.com#mostCommentedOnAllTime
[72]: http://www.developer.com/article.php/3896056
[73]: http://www.developer.com/article.php/777761
[74]: http://www.developer.com/article.php/3336751
[75]: http://www.developer.com/article.php/641521
[76]: http://www.developer.com/article.php/3896711
[77]: http://www.developer.com/article.php/3894316
[78]: http://www.developer.com/article.php/1495931
[79]: http://www.developer.com/article.php/3894566
[80]: http://www.developer.com/article.php/2109801
[81]: http://www.developer.com/article.php/3096831
[82]: http://www.developer.com/article.php/3417381
[83]: https://www.developer.com/sitemap.html
[84]: https://www.developer.com/contactus
Reference in New Issue View Git Blame Copy Permalink