Re. Documentation for various security levels

Subject: Re. Documentation for various security levels
From: geoff-h -at- MTL -dot- FERIC -dot- CA
Date: Tue, 13 Feb 1996 13:17:14 -0600

Greets, Karen!

In response to my request for more details on her problem
with single vs. multiple manuals, Karen responded:

<<Let's say our company is really the CIA and the software
we're developing is used to track and solve spy missions in
other countries.>>
Lets not... those guys have eyes and ears everywhere!
<grin... nervously>

<<...we have "clerks" who are entering data...
administrators who keep track of the missions ... the data
center, which is in charge of making sure the network
operates smoothly [etc.]>>
If the divisions are this clear, then independent
manuals for each category of user sounds reasonable. See
next point...

<<All this data is kept in a single database and accessed
with a single piece of software. What I suggest is putting
the clerk's instructions in one book, the administrator's
instructions in another book, and the data center's
instructions in a third.>>
The separate manuals approach will work so long as the
job descriptions don't overlap much or perhaps even at all.
("Disjoint sets".) If they overlap, then you have to give
workers in one nominal category parts of manuals for
another category. In a "secure" environment, there may well
be no overlaps, but in most jobs I've held, job borders get
vague and overlap somewhat. That might make this approach
complex for end-users to administer.
I'm also assuming that the user interface matches your
approach; for example, the clerks would never see the spy's
name and location data, nor for arranging to have a
double-agent liquidated, and would just see a blank form
for entering details about the anonymous spy. If this is
the case, then you have an even stronger argument for
separate manuals. On the other hand, if the user interface
reveals all kinds of menus, dialogs and buttons that every
user will see, even if they can't use these features, then
the interface poses problems that you can't solve simply by
using a single manual; better to modify the interface.

<<The clerks will not necessarily ever become
administrators, so they will theoretically never need to
know what the administrators do. ... What I'm mostly
concerned about is ease of use.>>
The ease of use concept is the key here. The
"minimalist documentation" school, which has a level head
about these things, supports you on this, and I can't argue
with their logic. If the tasks are clearly defined and
nonoverlapping, your minimalist approach should work fine.
The approach would break down for information that
isn't task based, such as providing a theoretical
discussion of how you should design such a security system
(e.g., an introduction for the administrators or
troubleshooters who you mentioned); in this case, the
context is more important than the steps you would use to
create the context, and minimalist documentation probably
wouldn't work.
Subsequently, once these folks understand the context,
a description of the steps that they would follow to create
the context could once again follow a minimalist approach.

<<It's hard enough getting users to read the manuals. If we
put in a whole lot of information that isn't applicable to
what the user is doing, he has a harder time finding what
he needs. ... The user would have to hunt for that
information amongst a bunch of stuff he doesn't -- and will
never -- need.>>
Again, a good comment, although a well-designed index
and a functional breakdown of the manual into appropriate
chapters or sections might resolve that problem
satisfactorily. For example, the Netware manuals form a
large set of relatively small books instead of a single
massive book. That approach might work well for you; it's
certainly less intimidating than a single 1000-page manual.
the tradeoff (in my experience) is that it can be painful
trying to determine which manual to look in, and that
suggests you need an overall "series index" of some sort,
in addition to individual indexes in each book. Then you
get the problem of hiding features from lower-level users:
again, you don't want curious clerks snooping around for
the "send spy X to Siberia" function.

--Geoff @8^{)}


Previous by Author: Re. Request for change
Next by Author: Re. Techwr-l only for writers?
Previous by Thread: Re: Re. Documentation for various security levels
Next by Thread: Re[2]: Re. Documentation for various security levels


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


Sponsored Ads