How to document multiple user roles? (take II)

Subject: How to document multiple user roles? (take II)
From: SIANNON -at- VISUS -dot- JNJ -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 4 Oct 2001 17:51:42

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

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

Geoff said:
<<That makes particularly good sense if you can supply "wizards" or
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
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

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 for more resources and info.

Previous by Author: Re. How to document multiple user roles?
Next by Author: RE: An observation about the writer-engineer relationship
Previous by Thread: How to document multiple user roles? (take II)
Next by Thread: RE. Can "either" be used if there are three or more selections?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads