Fwd: Re: how to add page numbers - documentation issues

[Kathi Bade]

As a card-carryin' member of the Society for Technical Communication 
and someone whose "day job" includes writing documentation on a 
proprietary piece of software to support a consortium of 26 agencies, 
I'm all in favor of involving the USER community in what you write. 
When we moved from our first system to our 2nd, I asked our members 
what kind of documentation they wanted.  They all said "we don't want 
to know how the system works - we want to know how to do our jobs!". 
So for that system and our 3rd and current system, I write a lot of 
"task-based" documentation, and it's very successful.

I involve my "customer base" both in the design and the review of 
documentation.  I always send stuff to at least 1 experienced user 
who will figure out what any inaccuracies or gaps; and a new user who 
will pick up any problems in clarify - or gaps that the experienced 
user may just have filled in for themselves.  I ALWAYS think about 
where the customer would expect to find that information before I 
write it, and I write it from the point of view of someone 
approaching it from that point.  And I never assume the user knows 
anything about the topic - in other words, I always include where to 
start and every step of the way.  Too many times, I find online help 
assumes you know all the steps to do sub-routines in a task, and the 
user doesn't always know that.  With online documentation, that's 
easy to do via a hyperlink - if someone remembers that the user just 
might need that information at that point of their search for 
information.

I too have incredible difficult finding how to do tasks using online 
help, and not just with OO.   I wish vendors would find a way to 
develop documentation that is more in line with the way the customers 
- not the programmers - approach finding information. Looking at the 
kinds of questions that come in via lists is a good way to start.

I hope the folks at OO - as well as all software vendors - will 
consider making documentation a high priority.  Early in my 20-year 
career in user support, I developed my motto:

User Support involves 3 things:  training, documentation, and direct 
customer assistance [help desk] - but the GREATEST of these is 
DOCUMENTATION, because it's available 24 hours a day, 7 days a week, 
365 days a year - and I'm not.  :-)

Kathi




>X-Original-To: OmniOutliner-Users at omnigroup.com
>Delivered-To: OmniOutliner-Users at omnigroup.com
>From: Curtis Clifton <curt.clifton at mac.com>
>Date: Fri, 15 Apr 2005 09:56:40 -0500
>To: Richard Rucker <rrucker at bellatlantic.net>
>Cc: OmniOutliner-Users at omnigroup.com
>Subject: Re: how to add page numbers
>X-BeenThere: omnioutliner-users at omnigroup.com
>List-Id: OmniOutliner Users <omnioutliner-users.omnigroup.com>
>List-Unsubscribe: 
><http://www.omnigroup.com/mailman/listinfo/omnioutliner-users>,
>	<mailto:omnioutliner-users-request at omnigroup.com?subject=unsubscribe>
>List-Archive: </mailman/archive/omnioutliner-users>
>List-Post: <mailto:omnioutliner-users at omnigroup.com>
>List-Help: <mailto:omnioutliner-users-request at omnigroup.com?subject=help>
>List-Subscribe: 
><http://www.omnigroup.com/mailman/listinfo/omnioutliner-users>,
>	<mailto:omnioutliner-users-request at omnigroup.com?subject=subscribe>
>Sender: omnioutliner-users-bounces at omnigroup.com
>X-RCPT-TO: <kabade at libraryconnection.info>
>
>On Apr 15, 2005, at 8:55 AM, Richard Rucker wrote:
>
>>Now, if anyone can find in the Help files provided with OO3 this 
>>level of detail of  "how to" information, I'd like to know how you 
>>found it.
>>
>>Curtis found it because he was willing to play with OO3.  On 
>>another occasion, I might have been willing to do that, but that's 
>>not my mindset when I'm working against a deadline (which I blew 
>>BTW).
>
>This is an interesting problem in general.  How much how-to 
>information can be put into help files and documentation?  The 
>number of permutations and combinations of options, settings, and 
>data is infinite.  The number of possible how-to scenarios is also 
>enormous.
>
>One approach to dealing with this problem is to simply have the 
>documentation enumerate all the options and settings and leave it to 
>users to figure out the "how-tos".  This approach is useful for 
>those of us who think in a certain way (like programmers), but seems 
>to be inadequate for people who think in other ways.  Most people 
>learn best from examples.
>
>Another approach is to try to guess the most common usage scenarios 
>and provide how-tos for those.  There are a few problems with this: 
>it is difficult to guess the common scenarios, documenting 
>_un_common scenarios may be wasted effort, and people may think that 
>the documented scenarios are the only possible ones.
>
>A third approach is just to grow a bunch of how-to instructions 
>based on what questions people ask.  A mailing list with searchable 
>archives seems a useful mechanism for implementing the third 
>approach.  This requires a community of people willing to ask and 
>answer questions.  The main problem with this approach is that the 
>expert users, those who can best extrapolate from limited 
>documentation or through investigation, sometimes become bored with 
>mailing lists that have many obvious questions. (Obvious to them, at 
>any rate.)
>
>I hope this isn't too off-topic.  But computer usability is an 
>interesting problem to me.  I think OmniGroup generally does a 
>wonderful job in the usability area.  I'm interested in others 
>perspectives on the whole documentation question.
>
>Cheers,
>
>Curt
>
>----------------------------------
>Curtis Clifton, PhD Candidate
>Dept. of Computer Science, Iowa State University
>http://www.cs.iastate.edu/~cclifton
>
>_______________________________________________
>OmniOutliner-Users mailing list
>OmniOutliner-Users at omnigroup.com
>http://www.omnigroup.com/mailman/listinfo/omnioutliner-users


-- 
Kathi Bade, User Support Coordinator-Lending Services
Library 
Connection                                                                
599 Matianuck Avenue, Windsor, CT 06095
Voice:  860-298-5322, ext. 1010
Fax:  860-298-5328
e-mail:  kabade at libraryconnection.info