RE: IBM Documentation (was CA Express and Life Certainties)

Create a keyed file by program/field and write a help window that reads the
file and displays the help text.  Add a function key that will check to see
if the user is authorized to update/add the help text.  If they are
authorized they can write there own help text.  (Train the
manager/supervisor and give them the ability to write THEIR help text for
THEIR people.)


Christopher K. Bipes    mailto:ChrisB@Cross-Check.com
Sr. Programmer/Analyst  mailto:Chris_Bipes@Yahoo.com
CrossCheck, Inc.        http://www.cross-check.com
6119 State Farm Drive   Phone: 707 586-0551 x 1102
Rohnert Park CA  94928  Fax: 707 586-1884

If consistency is the hobgoblin of little minds, only geniuses work here.
Karen Herbelin - Readers Digest 3/2000

-----Original Message-----
From: MacWheel99@aol.com [mailto:MacWheel99@aol.com]
Sent: Thursday, November 16, 2000 11:29 AM
To: MIDRANGE-L@midrange.com
Subject: Re: IBM Documentation (was CA Express and Life Certainties)


>  Sometimes I think the IBM manual writers spend too much time trying to
>  teach or lead you to determining how to do something, instead of just
>  saying "Here's how you do X".

This is a challenge that I am constantly struggling with.
My users have what should be a very simple question 
"Can we do X"
"Is there a problem doing X"
"Please modify so X occurs automatically from now on"

They are hoping for an answer from me that either is
Yes - no problem
No & here's why
Consider it done
It is ready for you to test & here's how

But the clarity with which X comes across to me is not there, which leads to

either 
excessive long windedness to determine exactly what X is so that I can 
resolve the user problem or issue, or
excessive long windedness covering what our options are in an essay how to 
deal with this reality ... most often with people who misconstrue printer 
messages

The user is seeing a message to do Y
The user replies as if the message was really Z
Al's revised printer user instructions include instructions to READ the 
message in its entirety then depending on WHICH standard scenario, here's 
what to do
but this still does not solve the problem of the user who thinks the message

was Z, replied with the correct response for Z, and got garbage, because the

message was really Y ... they do not want to READ the message, they do not 
want to READ Al's instructions, they just want the system to work without
any 
further hassles, and Al is in trouble for doing what the IBM manual writers 
are doing ... trying to educate the user how the system works & how to make 
it work for you.

I need some guidance on doing a better job of crafting documentation for a 
variety of user audiences.  I suspect the answer is a software tool that 
forces me to craft my words in conciseness, similar to these moderated 
internet lists.  If the IBM manual writer was constrained by midrange_L 
rules, the answers might be more to your point.

Alister William Macintyre 
+---
| This is the Midrange System Mailing List!
| To submit a new message, send your mail to MIDRANGE-L@midrange.com.
| To subscribe to this list send email to MIDRANGE-L-SUB@midrange.com.
| To unsubscribe from this list send email to MIDRANGE-L-UNSUB@midrange.com.
| Questions should be directed to the list owner/operator: david@midrange.com
+---