Reading Room: Great Technical Writing Series


 

Home | Contact | Site Map

Navigation:  Home -> Reading Room -> Great Technical Writing Series


Feel free to distribute any of the articles in this "Articles Library."  The only condition is that you do not modify, delete or add to any of the material in the article.  You must copy, send or publish the article in its entirety, including the Resources section of the article. 

Click on the article's title to read the article.


Content is King (2006-08-20)

We've lost sight of the two most important aspects of our User Documents. This loss of focus causes our organizations loss of money and business.


From Feature to Expensive Flaw (2006-08-30)

Your product's unexplained features can turn into costly flaws.  This article describes three real-world products with just such "features."  It presents ways you can prevent these feature-to-flaw conversions by improving the User Documentation for your products.


Has Anyone Ever Used Your Product? (2006-09-14)

Product documentation gives the feeling that nobody has ever used the product.  Most documentation:

  Before you release a product,  have some people use it.  From these "test users" get solutions to problems, tips and knowledge that would help your real-life Users.  Put that information in your User Documentation, and on your product support Website.


Banish These Two Attitudes (2006-09-25)

Two attitudes of many Technical Writers result in less than ideal User Documents.  Those two attitudes are:

This article describes these attitudes and presents methods for overcoming them.


The Two-Edged Sword of Reader Experience (2006-10-24)

When we write User Documents we rely on our Reader's/User's experience to simplify our work.  This can cause problems for the Reader. This article will discuss the effects of Reader experience and how to minimize the negative effects of incompatible experience, and how to handle the writer's assumptions about the Reader.


Sell Your Readers On What's Important (2006-12-04)

Our humdrum, sterile headings and writing manner do little to encourage our Users to read parts of the product documentation that would be especially beneficial for them.  This article presents two real-world examples, how they fail their users, and how to correct the problems.


Make Your Product Fit (2007-02-15)

Most product documentation sounds like their product is the only thing in the User's life.  Such thinking results in User confusion and dissatisfaction.  This article presents three real-life examples of this attitude, and what should be done to remedy these unfortunate situations.  The article concludes with some techniques for the writer.


Improve Document Searches (2007-03-14)

Searches in User Documents (manuals, etc.) often fail because the Reader uses different words for a concept than the author uses. Since the Reader's words do not appear in the document, the document search mechanism cannot find them, resulting in frustration.   This article describes a User-friendly technique for improving searches, without having to change the Users' behavior or the search software.


Improve Your Readers' Access with a Visual Index (2007-06-06)

People are visual creatures.  They look at your product, and see, for example, a button or display.  They want to find out about that control or indicator.  A Visual Index is a simple but powerful document access tool that enables your Readers to find the information that they want.

 This article describes the Visual Index concept and tells how to create one for your document.

 


User Document Headings Should Be Guideposts, Not Advertisements  (2007-06-28)

Most heading are designed to entice us to read further.  Headings in User Documents should enable your Reader to decide whether or not to continue reading that section.  Make it easy for your Reader to understand your User Document by using effective headings. 


Tell Your Users What to Expect  (2007-09-18)

In your User Documentation, you direct your Reader to perform tasks with your product.  If you don't tell your Reader what to expect when performing those tasks, you will have a baffled Reader, resulting in dissatisfaction and expensive calls to technical support.

 


The User-Product Life Cycle: A Tool for Generating User Document Topics (2007-10-25)

The User-Product Life Cycle (U-PLC) is a powerful tool for the User Document writer.  Use the U-PLC to generate the high-level topics for your User Document.