Re: User Manual par excellance

Subject: Re: User Manual par excellance
From: Jefro <jefro -at- jefro -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 20 Sep 2005 10:56:42 -0700


It sounds like the boss is making the assumption that users will be reading this book in linear fashion, from start to finish. While there are some propellerheads about who like to do such things---I do this with all manuals out of professional curiosity---I have found in my vast experience that about 95% of the readers of technical information do NOT do this. They look in the TOC or index and attempt to go straight to the section that will tell them how to get from A to B. Some dispense with actually looking things up and just try to get by looking at the index before calling customer support.

Case in point: once in the distant past I put an easter egg in the front matter of a manual and sent it to reviewers, then forgot about it and it went to 30 or 40 customers. Not on purpose---well, maybe a Freudian slip. It was sufficiently funny that it should have been caught immediately by anyone reading the material. Not a single word of feedback.
In my opinion a well-written manual, e.g. reference manual, programmer's guide, etc., is completely independent of whatever glitzy goo appears at the beginning. The manual answers questions, one at a time. It is not meant to be an exciting read.

Now... armed with this opinion, take a hard look at the document itself and figure out what question it is trying to answer. Then, as others have said, go back to the boss and find out what they want, in a non-confrontational way that belies your desire to do the job right.
Best of luck!

Jefro


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l

Doc-To-Help 2005 converts RoboHelp files with one click. Author with Word or any HTML editor. Visit our site to see a conversion demo movie and learn more. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.



Follow-Ups:

References:
Re: User Manual par excellance: From: Denise

Previous by Author: Re: Advice/survey on professional development?
Next by Author: Re: Corporate World vs. Small Company: Considerations?
Previous by Thread: Re: User Manual par excellance
Next by Thread: Re: User Manual par excellance


What this post helpful? Share it with friends and colleagues:


Sponsored Ads