Effective Engineering 
                Consulting Services
   
                                           "Helping Engineering Excel!"

Home
Our Premise
The Problem
Our Promise
Our Approach
Our Deliverables
Case Study
Our Results
e-Newsletters
Our People
Contact Us
Photos

 

Back to e-Newsletter Archives:

 Effective Engineering e-Newsletter – 11/2/2006

This is your monthly e-Newsletter from
Effective Engineering Consulting Services (www.effectiveeng.com).  If you would like to receive Effective Engineering e-newsletters as they are published, please send an email to e-newsletter@effectiveeng.com, and we will add you to our distribution list.  Comments and suggestions are welcome and encouraged!


eN-061102:


RTFM! – Read The Friggin’ Manual! – An Ode to Technical Writers

  By Tom Dennis – President, Effective Engineering [tdennis@effectiveeng.com]


You’ve just bought a new electronics product and you’re starting to play with it.  You’re anxious to try out a new feature that you’ve heard about that’s really clever.  You try one thing after another, but you just can’t get it to work.  You get more and more frustrated, but you figure you’ll just keep trying.  The user’s manual is sitting right next to you, but you don’t really think you need a manual to get this to work (manuals are for wimps!).  A colleague walks by and asks, “What’s the matter?”, and you tell her that you’re trying to get this really clever feature to work, but it doesn’t, and you’re beginning to think the product is defective.  Your colleague looks at you strangely and barks, “RTFM! – Read The Friggin’ Manual!”  Embarrassed, you do and very quickly get the desired result.

Unsung in the development of new products are the Technical Writers.  These are the people who make sense out of complex products and present needed information about the product in a language everyone can understand.  This is my ode to the unsung heroes, the Technical Writers.

There are good and not so good Technical Writers.  When they are not so good, reading a manual can be an exercise in water drip torture, or something far more effective than the most powerful prescription sleeping pills available.  When they are good, they are amazing, making what could be mind-numbingly boring descriptions of the steps necessary to set up or use complex products into an experience as enjoyable as reading a “can’t-put-it-down page-turner novel” (You know who you are, Katy Weller!). 


The amount of work that is required to learn about the product and its applications and to present this in a readable and meaningful fashion can be enormous, and involves the Technical Writers interacting with people in engineering, product management, quality assurance, customer or technical support, sales, and most other organizations in a company.  Technical documentation is put together under demanding timeframes, and must be revised numerous times as features are added, deleted, or changed.  It must be ready to go in time to be packaged with the product, and must be updated to reflect changes over the product’s lifetime.  Whether used or not, good (or even not so good) technical documentation is a critical element of any product’s development.

I have asked two Technical Writers who I greatly respect, Katy Weller, who I know from my days at Russound, and Joe Zidek, who I know from my days at Cabletron/Aprisma, to help me with their insights on the secrets to great technical writing.  These are incorporated into the following, and I greatly value and appreciate their input.


First, let’s discuss the Technical Writing process to enable delivery of great documentation. 

As with any development effort, the development of good technical documents must start with a good plan (see eN-031023 – Development Methodology: Failing to Plan Means You Are Planning to Fail!).  This includes identifying what kinds of technical documentation are required, which means determining who your audience is and what documentation they will need.  It also includes identifying the key milestones, deliverables, and schedules for these documents (and how they fit into the overall project schedule), following an internal style guide so that consistent documentation can be delivered, defining documentation feedback mechanisms to determine what customers like or don’t like about their product information, and utilizing technical writing tools that enhance productivity in creating technical documentation.

Technical Writers should be involved as early as possible in the development process to understand what the product is, who will install it, who will use it, who will repair or maintain it, etc.  To this end, Technical Writers should author the Data Sheets (technical specs, not engineering specs) both to better understand the product and to determine if any further training on the technology involved is needed.  Experience shows that a 1 to 4 page Data Sheet can take 10 to 20 times longer to write (in hours per page) than any other kind of manual.  Since they are used to sell the products, they must be totally accurate and easily interpreted.  Competitive products often play a part in how products are positioned, and so are usually referenced directly or indirectly in the Data Sheets.  Working on the Data Sheets aids the Technical Writers because they become part of the evolution of the product so that by writing time they are already somewhat expert on the products.

Know thy audience and write to them.  Technical Writers need to write to the audience associated with the specific manual.  An Installation Manual should be written for the person installing the product, who is not generally the person who will be using the product.  It should enable the installer to do his/her job thoroughly, but as quickly as possible.  A User Guide should be written for people who will be using the product routinely.  A Maintenance Guide should be written for someone trained specifically to maintain and/or repair the product.  Technical, Reference, or Administrator Manuals should be written for engineers, programmers, or system administrators.  Etc.

Technical Writers should create technical documents (pamphlets, manuals, getting started guides, etc.) that the user will be attracted to and actually use.  Keep them simple.  Use color.  Experience shows that color can make things clearer and results in more positive reactions.  Make them unique.  Use illustrations/ pictures instead of text.   The more that illustrations/ pictures are used, the less text that will have to be translated if the product will be sold in other countries.  [Note – Translation is a separate topic that won’t be addressed here, but if you have to make your technical documentation available in different languages, this needs to be thought out well in advance.]  While Technical Writers should use as many illustrations, photos, screen shots, etc. as applicable, they should not overdose on them.  Effective illustrations can be interpreted by users without them having to read text, especially if call-outs are used.  Each figure should have a purpose, and should be as close to the related text as possible.  Text should reference every figure used, but avoid sending users back a few pages or chapters.

The writing itself is the fun part!  After the document planning and product refinement by engineering, the writer gets to use her/his talents to describe the installation, use, and maintenance of the product, hopefully in as few words as possible.  Manuals should be concise and correct.  The first draft of a manual will not be perfect, and the Technical Writers should not try to make it so.  They should do their best and produce a draft that can be reviewed by key reviewers, typically engineering, marketing, support, manufacturing, and most importantly QA. 

Review of technical documentation is critical, but the reviewers’ objective should be to evaluate the drafts for technical content, not typos.  They should review whether all areas of the product are explained, whether the draft is accurate, whether there is too much or too little information, and whether the document is organized correctly.  Reviews should be conducted at various points along the way, but critically they should be done both before and after the final draft. [Note: Experience shows that the overall best reviewers are the QA people (see eN-050505 – Make Quality a Full Member of Your Team!).  Their job is to know the product thoroughly and they check that every aspect of the product works as detailed in the engineering specifications, so to them, the documentation draft is a reflection of the product.  They can do further testing of the product using the technical documentation.  This helps to test both the product and the documentation.  Technical Writers and QA testers should be good teammates, both trying to complete the product with their efforts.] 

Editing is generally the least understood area of the documentation process, at least to people not familiar with it.  To them, it is extra time and money that can delay the documentation even more. [“Editors don’t write, so what good are they?  They don’t produce anything!”]  The same can generally be said about managers; they are overhead.  However, a good editor is invaluable to a Technical Writing group.  An editor objectively evaluates a document and makes it more accurate, thorough, and easier to read and interpret so that the final user receives a manual that presents information in an orderly step-by-step process that is easily understood and doesn’t contain obvious or confusing errors.  But above all of this, a good editor is invaluable because she/he provides real-time feedback to Technical Writers on what skills need improving (e.g. grammar, punctuation, style, format, flow, sentence structure, paragraph organization, etc.).  This is how Technical Writers become better writers.  The Technical Writing group should continually improve so that their productivity, document quality, and “document greatness” all increase.

Another key Technical Writing area is fulfillment and delivery.  Once written, reviewed, and approved, technical documents need to be prepared for inclusion with the product, whether in hard copy, CD, or on-line versions.  If this is being done internally, it is essential that the time, efforts, and resources to provide the needed documentation are included in any schedule.  If this is being done by an outside vendor, then it is essential that a reliable vendor be found; one on whom you can depend to deliver the quality and quantity needed.


So much for the process issues.  These can help in creating good documentation, but will not automatically lead to great documentation.  What makes for great documentation is the passion of the individual Technical Writer.

To create great technical documentation the great Technical Writers must be curious, with an inquisitive nature.  They should get caught up in the product and channel their own curiosity about the product into the technical documentation.  They should present the fun aspects of the products in such ways that the users of those documents will share in that fun.

To be effective, great Technical Writers need to get out of their seats and meet face-to-face with the many people involved in creating the product.  If they remain satisfied with sitting in their cubicles relying on being fed information via electronic communications and avoiding face-to-face interactions, their manuals will be as passive as they are.  They need to talk to as many people as possible who are involved in the project.  They will almost certainly pick up information tidbits that didn’t/ wouldn’t just get passed to them.  Just because they are “supposed” to get all needed information doesn’t mean they will.  They need to ask as many questions of as many people as possible.  They will likely bring up some points that no one has yet thought of. 

Great Technical Writers will get their hands on the product and use it as if they were the installer or end user or whoever the documentation they are preparing is intended for.  Reading a product specification will never take the place of handling the actual product.  What’s fun about the product?  What’s confusing?  What’s surprising?  They need to know the product deeply enough to explain it fully to other people on their own and without help from the “experts”.  If they don’t fully understand it, how can their writing explain it?  They need to put themselves in the customer’s place.  What is the user experience (see eN-060105 – How Do I Get This D@#% Thing To Work?) and how can they convey that experience in terms that customers will not only understand, but enjoy?  Once the manual is done, they will take it and test the product themselves by following what they’ve written in the manual.  They’ll also sit with the QA testers and go through the manual and the product to see what they may have left out or missed.

The technical documents have a job to do – to help the installer get the product installed and running properly, and to guide the user in how to use the product to its best ability.  For each piece of information, they will determine their audience (e.g. installer, user) and write the technical documentation accordingly, in ways that make using the manuals a true pleasure for those users.

A great Technical Writer knows what great documentation looks like and what a pleasure it is to read and use.  They will find such documentation from other outside products and build upon what is great and move away from what isn’t (see eN-030605 – Learn from Good Role Models; Learn More from Bad!).


So when you buy a new product, before you get too wrapped up in playing with the product, read the friggin’ manual!  And recognize that a lot of talented people have put a lot of effort into putting together the information you need to get the product to do all it can do and be all it can be.



Copyright © 2006 
Effective Engineering Consulting Services, All Rights Reserved

Back to e-Newsletter Archives:

   

Society of Professional Consultants

  

Copyright © 2002-2013 Effective Engineering Consulting Services, All Rights Reserved