Re. Documentation for various security levels

[geoff-h -at- MTL -dot- FERIC -dot- CA]

 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^{)}