RE: How to document multiple user roles? (take III)

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Shauna Iannone provided additional information on the problem:

<<You actually summarize the main problem: this system doesn't define things
quite the same way as would be expected.>>

Where the software doesn't define things in the same way its users would
define them, you can expect all kinds of cognitive dissonance. This is a
good case of where you should redefine the software to match the user's
expectations, not vice versa; since you're not necessarily changing any of
the underlying code and are only modifying the interface, this shouldn't be
impossible to sell to the programmers.
   
<<We're trying to transform two legacy paper processes into a single
transactional electronic one, without a 
consistently-defined workflow for either of the original processes.>>

For a few more details on the kinds of problems this approach poses, have a
look at my upcoming article on the techwr-l site (may not be available for a
week or so): Hart, G. 2001. Policies, procedures, and paralysis.
www.raycomm.com/techwhirl/usersadvocate_policies.html

<<Add to that a previous flux in management that allowed several major
components to be developed by different programmers in their own personal
silos, without enforcement of a consistent underlying model for the
design.>>

Time to point out to the development manager that this situation creates a
maintenance nightmare. If you expect to be revising the software
periodically in coming years, it's crucial to create a well-documented,
consistent, underlying architecture: "you can't build a durable house
without a firm foundation". One reason Microsoft has been unable to fix the
autonumbering program in Word (and why Corel rewrote WordPerfect virtually
from scratch at one point) was because the underlying code became such a
nightmare that it was impossible to work with. This is also why PageMaker 7
was only released more than 2 years after 6.5 came out and why Adobe focused
its efforts on InDesign: an Adobe rep told me that the underlying code had
become such a disaster that they felt it was easier to scrap the whole
product and start over again from scratch, using more modern programming
techniques. (The underlying code for PageMaker is probably 17 years old in
some places by now.)

<<The problem is that the "role" I need to describe is a database term, not
referring to the user's responsibilities or "role" in the workflow, but
rather representing a compartmentalized set of privileges assigned to
specific functions in the app.>>

Again, this doesn't match the user's experience: you should never force
users to rewire their brain to match how the software works. Our job is to
conceal that technology beneath a friendly veneer that makes sense to the
user. When we can't do that, it's a sure sign that something is wrong with
the interface.

<<Multiple app's point to the same dB, and use the roles to control what
functions are accessible to the user. The user must be assigned the roles
they need to accomplish the tasks they are assigned.>>

In this case, it seems completely unnecessary from the user's standpoint to
even mention roles. Users each have a specific task to accomplish with each
application when they access the database. Their formal role/name is
irrelevant; all that's relevant is what they need to know to complete the
task. Given that each application seems to have a slightly different way to
interact with the database, it seems to me that the simplest way to solve
your problems is to document each application individually and ignore the
whole concept of roles. If they're assigned a role, they don't need to know
what that role is called: all they need to know is the task they've been
assigned, and that they can accomplish all the steps necessary to complete
the task. If that's not the case, then you've just discovered a major
usability bug in the software.

<<The app. itself doesn't have help because it had been decided not to
include it... My attempt to convert our training manuals into a helpfile is
a means to sneak in some help through a less painful "since I have this
already here, why not stick a button in there linking to it" approach.>>

That makes good sense once you overcome programmer resistance to inserting
the help topic IDs. Not a trivial problem, but also not one that you can't
overcome with gentle persuasion. Once they figure out how easy it is,
they'll grumble and do it.

<<It will not be context-sensitive at first (I'll make it topical with
available browse sequences)>>

For a previous help project, with no resources to create wizards and a
specific request not to include a tutorial (???), I solved this problem by
adding a help topic that showed a high-level overview of how to accomplish
the main task (building a decision-support model), with a link in each step
to the portion of the Help file that explained the details of that step. In
the introductory paragraph to this topic, I said: "To find out details on
how to accomplish each step, click the included link. When you're done,
click the Back button to return to this sequence of instructions."
Primitive, but it worked amazingly well.

<<This goes back to the "How do you deal with a need to change a corporate
culture" question.>>

By clearly pointing out the drawbacks of the current approach and the
benefits of changing it. Yes, it will be slow, but everyone will thank you
for it once they make the change.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Planning to attend IPCC 01, October 24-27 in Santa Fe?  Sign up by
October 3 and get a substantial discount!  Program information, 
online registration, and more on http://ieeepcs.org/2001/

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

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