RE: Who's the User? (You're the user!)

["Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>]

Shauna,

I don't know if this is entirely applicable to your situation, but we did
encounter something similar for our middleware product a couple of years
ago.  Since in our "real world" system administrators are client power users
who've just been around longer than other folks (or low-level managers), and
know a few more tricks with our products, we were able to help our
developers understand pretty quickly that what might be obvious to those of
us working on the product, isn't necessarily obvious to those that have to
install it and maintain it in actual production somewhere.  Using the tactic
of stroking their egos seemed to help. ("It's pretty cool what you did here,
but I'm not sure so-and-so at this client would understand it without
tutoring" or some such).

Maybe you could tell them since they're so irreplaceable, you want to
enshrine their knowledge as a tribute? ;)

Hope it helps!

Connie P. Giordano
Senior Technical Writer
Advisor Technology Services
A Fidelity Investments Company
704-330-2069 (w)
704-330-2350 (f)
704-957-8450 (c)
connie -dot- giordano -at- fmr -dot- com <mailto:connie -dot- giordano -at- fmr -dot- com> 
 
"I am always doing that which I can not do, in order that I may learn how to
do it." - Pablo Picasso 


-----Original Message-----
From: SIANNON -at- VISUS -dot- JNJ -dot- com [mailto:SIANNON -at- VISUS -dot- JNJ -dot- com]
Sent: Thursday, April 04, 2002 4:22 AM
To: TECHWR-L
Subject: Who's the User? (You're the user!)



Joe Sokohl writes in another thread:
> Part 2: Where is the User?
> In all the discussion, which is extremely practical and implementation 
> oriented, I'm still missing any audience analysis...and document 
> purpose. 
[...snip...]
> Although underwriters use the system to provide information to 
> prospective buyers of insurance, who uses the documentation? Why? Where?
> How? 
[...snip...]
> Are they being created to meet a legal requirement, or 
> are they documents that different programmers can refer 
> to when they are creating new utilities?
> Let's remember that programmers are users, too.

Thanks for mentioning this...it hit me from another angle on the checkbox 
thread, and after reading your post, and trying to get information from one 
of my SMEs on an app. this morning, I think I know why, now.

Have any of you found, in your experience, whether overt clarification of 
the audience with your SMEs helps them provide you with more thorough 
information? I'm seeking a diplomatic solution to a scenario that I've 
encountered more than once now (from different sources under different 
contexts, so I'm thinking maybe it's not just a fluke of one person's 
opinion).

I've had a difference of opinion with a developer (or two) that I believe 
affects the quality of one of my docs. I think it might be resolved if the 
developer was to see himself as a user of the product he is creating...or 
maybe see someone *besides* him as the user, actually.  I'm having 
difficulty getting the idea across to the developer in question, so I'm 
thinking there must be a better way to convey the point than how I've 
approached it so far.

The Context: in one system, an application performs functions in the 
background on a server, and the only GUI component it has is not for the 
end users of the system (they have their own application), but rather for 
the system administrators to set configurable constants or perform cleanup 
and maintenance functions (an "administrative interface"). The problem I've 
encountered is getting details on this GUI.  Because it is "not a user 
interface" (the developer's words) it doesn't need to be covered in any 
great detail, in his opinion. In this system, the developers are the system 
administrators, so they occasionally don't think I need to document 
something for which they are the only users. In my opinion, if the 
developers all got hit by a bus on the way to lunch, whoever replaces them 
is going to want to know how to use that GUI, so I want it documented as 
thoroughly as possible. The only detailed standards for the doc set in 
question are those I've applied myself, so I can't just point to an 
existing standard and say "because it says so", and I'd like to avoid being 
confrontational if possible (if not possible, oh well, but I figured I'd 
ask about diplomatic solutions first).

Have any of you encountered something like this, and have you found a way 
to get this point across without being unnecessarily confrontational?

Thanks!
Shauna
 


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

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