TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Keith Hood wrote:
> I think Paul's list is perfectly valid for a reference type of document, although 2 and 3 seem redundant to me.
>
> Janice's list, to me, reads like it's closer to a marketing approach about deciding what to put in the documents. It seems predicated on putting more into thinking about the nature of the users.
>
> I think for a procedural guide the list has to be different because
the information has to serve different purposes. Here's my list for a
procedural document, in no particular order:
>
> 1. What level of expertise can be expected of the user?
>
> 2. What is the user trying to do with the item?
>
> 3. What does the user need to know *before* he tries doing that?
(Could be restated as, What are the traps the reader could fall into?)
>
> 4. What results should the user see when he does it right?
>
> 5. What should the reader do if something goes wrong? (This one is
usually never answered, or answered indirectly at best by placing more
emphasis on #3. The places I've worked, guidance on how to deal with
errors is almost never included in any documentation, electronic or hard
copy, because there isn't time to build in any fault tolerance.)
>
I'm not quite sure how your list and mine differ.
Your points are all good ones but most of them
are covered under the answer to the question "What
information do they need in order to use the product
effectively?"
I don't think it's Marketing to try to tailor your
documentation to the person who is most likely to
be reading it. In order to identify what is going
to be done with your product, and what knowledge
you can assume and what knowledge you need to
explain, you pretty much need to know something
about the majority of the people who are likely
to be reading the doc and using the product, imho.
-- Janice
***********************************************************
Janice Gelb | The only connection Sun has with
janice -dot- gelb -at- sun -dot- com | this message is the return address
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at: http://www.doctohelp.com/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
