Re. How to document multiple user roles?

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

Writer Whirler wonders: <<I am writing a user guide for an application whose
users can have one of  three levels of permissions: A, A+B, or A+B+C. The
business wants me to write one user guide that incorporates all functions,
instead of three separate guides, which is fine with me... How much should I
explain the three roles a user can have?>>

As in any other place where you create separate roles, you need to define
these roles somewhere. A logical place would be in the introduction to the
software, plus in the tutorial--and, of course, in the online help. Once
you're actually developing the docs, you've got a tougher challenge because
the right way to handle the situation depends on how people are going to use
the docs and the nature of the content. The ideal solution, of course, is to
have the user log into the software once, identifying their permission
status when they do, and thereafter, only display the software functions
that someone with that permission level could use; if they can't see it, you
don't have to worry about them finding it in the docs, and if they do find
it, then maybe it'll motivate them to obtain a higher level of permission.

For example, let's say you can do up to three things to some object, with
the things that you're allowed to do defined by your permissions level. In
this case, it might make good sense to write as follows:
Dealing with the Ziggurat object:
- Anyone can touch it.
- If you have B permission, you can knock on the door.
- If you have C permission, you can enter when the door opens.
This could get awfully repetitive, so you might want to consider icons or
other formatting rather than "if you have X permission".

Another example: In this case, all the A, B, and C tasks don't overlap. If
you have A permission, you'll never do B or C tasks, and thus don't need to
know about them. That means you can group the tasks into three categories:
A, B, and C.

And yet another: In this case, A, B, and C tasks may be all closely related.
Consider, for example, file management: everyone should be able to see the
files (A), only some people can modify and copy files (B), and only
administrators (C) can delete files. In this case, you might have a single
topic (files) with three subheadings: things everyone can do (A), things
only the creator of the file can do (B), and things only network
administrators can do (C).

Different problems, different solutions.

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

"It is at this point that Shaftoe makes his Big Decision. It is surprisingly
easy--but then, really stupid decisions are always the easiest."--Neal
Stephenson, Cryptonomicon

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

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.