How to document multiple user roles? (take II)

[SIANNON -at- VISUS -dot- JNJ -dot- com]

I said:
<<[snip]These responsibilities may not always directly map to a
specific assortment of functions.>>

Geoff said:
<< 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.>>

First:  your comments were helpful (and you were right about E; I forgot 
that one didn't apply a constraint to the navigation of the screens) -- 
this is just an expansion of the issue's variables, not an argument against 
the proposed solution(s).  You actually summarize the main problem: this 
system doesn't define things quite the same way as would be expected.   
It's a project where every person currently working on it inherited it from 
people who have long since escaped, and we're trying to accomplish things 
not yet commonplace in the industry.  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.  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. This is why my 
documentation has included a great deal of technoarchaeology and 
reconstructionist data and system modelling.  (Welcome to my Hell...)

Second: 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. 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. The assortment of tasks do not match the user's "role" in the 
workflow, but rather may be used by multiple "roles" in the workflow. It's 
a many-to-many relationship, in a way, and the process loops back to the 
middle on occasion, to boot.  I think I'd be more concise describing it by 
way of example:

User roles in the workflow:
--Usertype A has the WorkflowRole "Operator" 
     for MachineType A producing Widget Brands A or C
     and applies to 16 actual people using the app.
--Usertype B has the WorkflowRole "Operator" 
     for MachineType B producing Widget Brand B
     and applies to 8 actual people using the app.
--Usertype C has the WorkflowRole "Inventory Control" 
     for MachineTypes A & B producing Widget Brands A, B or C
     and applies to 2 actual people using the app.
--Usertype D has the WorkflowRole "BeanCounter"
     for Widget Brands A, B or C
     and applies to 3 actual people using the app.
--Usertype E has the WorkflowRole "CounterCounter"
     for MachineTypes A & B 
     and applies to 2 actual people using the app.
--Usertype F has the WorkflowRole "WidgetCounter"
     for MachineType A producing Widget Brands A or C
     and applies to 4 actual people using the app.
--Usertype G has the WorkflowRole "WidgetCounter"
     for MachineType B producing Widget Brand B
     and applies to 1 actual people using the app.

AppRole 1 = can view data on all screens, and can print labels
AppRole 2 = can use Add Foo function, and Remove Foo function
AppRole 3 = can grimblize product
AppRole 4 = can change lot status to "DoItAgain"
AppRole 5 = can ungrimblize product with status "DoItAgain" 

Usertype A has AppRoles 1, 2, 3, 5
Usertype B has AppRoles 1, 2
Usertype C has AppRoles 1, 2, 3, 4, 5
Usertypes D, E, F & G have AppRole 1

The elements of the App. are visible to all registered users, but access to 
certain cascading dialog boxes and the views or functions they contain is 
restricted by lot status and Widget type. Restriction of a user from 
performing a function is accomplished via required electronic signature 
when the event is triggered by the user clicking the right button(s). Add 
Foo and Remove Foo can occur to ungrimblized, grimblized or re-grimblized 
widgets, at any time.

The Add Foo and Remove Foo functions use two different screens (Add and 
Remove).  Each screen looks and functions differently depending on whether 
you enter Widget type A, B or C, due to packaging constraints.  They also 
react differently depending on whether or not product has been 
re-grimblized. Adding too much Foo can make part of the lot un-grimblized, 
but not always. Ungrimblized product must be grimblized before it can 
proceed to the next step of the process.

...and this is just the part used by the one app.--there are other app.'s 
running in parallel off the same dB, using the same "role" definition 
structure -- e.g., Usertype B above also has AppRole 6 & 7, which are used 
by another app. to accomplish another function before the widgets even get 
to this part of the process.

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

Geoff said:
<<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.>>

I wish I could do that.  The app. itself doesn't have help because it had 
been decided not to include it (some folks thought we didn't have enough 
time, and the users didn't specifically ask for 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.  It will not be context-sensitive 
at first (I'll make it topical with available browse sequences), but if I 
can get them to point to it, I can show how context-sensitive help could be 
incorporated less painfully over the next several revisions. (There is no 
"final version" of this app.--it will evolve for another couple of years 
before all the equipment they hope to plug into it is built and added in, 
and all the "oh and another thing" pieces have been ironed out.)

This goes back to the "How do you deal with a need to change a corporate 
culture" question.  It will be slow, but since this team never even *had* a 
tech writer until I came in, and since many development teams here *still* 
don't get tech writers at *all*, it's nothing to be alarmed at.  It's just 
a typical corporate IT sub-dept. going through growing pains.


Shauna Iannone
-----------------
Any opinions expressed in this message are mine (All mine!), and should not 
be mistaken for the views of my employer.


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

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.