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

[MacWheel99@xxxxxxx]

>  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
+---