How to document multiple user roles? (take II)

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

Shauna Iannone reports a similar problem: <<Internally developed and used
software... covering multiple functions in one interface. A, B, C, D and E
are roles that allow the user to complete different... functions. Role A is
"view only" access that everyone using the system must have. Role E is a
function that everyone can access, regardless of their responsibilities,
because it does not require special security access (performs action with
output, but does not change data).>>

For a start, roles A and E seem to be identical, since everyone can do both.
Given that this is the case, this falls into the category of "things
everyone can do", and might even deserve its own section "Introduction to
the basics". It certainly doesn't need to be distinguished as separate
roles. This simplifies your task because now all you really have to worry
about are C, D, and E.

<<The other roles... change the data... Users... can have different
assortments of these roles assigned to them, depending on their
responsibilities. These responsibilities may not always directly map to a
specific assortment of functions.>>

See my signature line: how can a role be separate from a responsibility in
any sane workflow? <g> In this case (if I've understood you properly), the
functions cannot be independent of the responsibilities: if someone is
responsible for doing something, then doing that something becomes their
role, and they must have access to all the functions that let them fulfill
their responsibility. I suspect that part of your problem arises from not
clearly defining what you mean by "roles and responsibilities and
functions". In fact, if you look at everything in terms of tasks, and forget
the name games, you'll probably find it much simpler to analyze the problem.

<<roles C and D apply to a function that can be used for two different...
products (which must be differentiated due to different proccessing
constraints...), and thus the function operates differently (including the
prompts and options available) depending on which of these types of products
are entered>>

If the two products (and their associated functions) are much more different
than they're alike, then you need entirely separate documentation for the
two roles. If they are mostly the same, but with occasional differences,
then you can often take the following approach:
Step 1. Same for both.
Step 2. Same for both.
Step 3. Same basic step for both, but with the following difference:
	Product 1. Do A.
	Product 2. Do B.
Step 4. Same for both.
Step 5. Same basic notion for both, but with the following difference:
	Product 1. Do A.
	Product 2. Do B.
etc.

<<I am currently pushing to use an online Help format instead of the paper
manuals...>>

That makes particularly good sense if you can supply "wizards" or similar
integrated assistance that walk users through a task one step at a time.
It's doubly sensible if the users must "log in" to determine their access
privileges, and subsequently only see the screens they're entitled to see.
Even if you can't do something this sophisticated, you can at least provide
fully context-sensitive help that fakes the same effect.

<<However, at the moment I'm having to do this with a paper manual.>>

I suspect if you make a much clearer breakdown of the tasks and the
functions required to perform those tasks, you'll see the structure much
more clearly than if you worry too much about roles.

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