A question of structure? Two platforms x two user types.

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

Becca Price is developing <<... an outline for a proposed reorganization of
our Administrator's Guide... we sell a database product that runs under
either Oracle or SQL [the platforms], so some of our procedures are really
two: setting up the user (in Oracle) and setting up the user (in SQL) for
example. My problem: we have 2 kinds of users: administrative users, and
"other" users. You create them differently in the database, so they are
separate procedures.>>

In effect, you have four more or less unique procedures: two each for Oracle
and SQL. If you produce a separate manual for each platform, independent
manuals might offer a convenient solution, since the Oracle users can simply
file the SQL manual and never look at it again, and vice versa. More
importantly, they will never have to wade through or tune out the text for
the other product. That assumes, of course, that the SQL and Oracle versions
overlap so little that it makes no sense to reuse text extensively (which
would argue in favor of a single manual). The obvious compromise is a single
manual with separate chapters for each platform; that's particularly
beneficial for you (if not the user) when you don't sell different product
configurations, since coordinating print runs for different manuals to be
inserted in different boxes can be logistically nightmarish at the
production stage (e.g., you might end up with thousands of unused Oracle
manuals if demand for that version proves lower than you expected). That's
not a problem if the guides are online help, of course; the user selects
which manual or manuals to install during the regular installation.

<<Should I group them by platform or by task?>>

By both. <g> Think of it from the user's perspective. First, consider the
platform. If you're administering SQL, any text related to Oracle must
either be filtered out while you seek the nuggets of information that relate
to SQL; if it's simply in the same manual but a different chapter, it serves
no useful purpose as far as you're concerned, and only makes the manual
twice as large as it needs to be for your purposes. That's not a major
problem, but might prove annoying to some. Second, now that you've performed
that initial segregation by platform, you must segregate the information a
second time by task (i.e., by type of user), and for exactly the same
reasons: if there's little overlap in instructions between types of user,
and I'm working on User Type A, get the information for User Type B out of
my way so I don't have to skip over it or force myself to ignore it. Again,
if there's substantial overlap between the instructions for the two user
types, it may make more sense to provide only a single guide (easier to
write, update, and print), and that's particularly the case if the docs are
online help and you can customize them during installation.

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

"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein

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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See
http://www.infomap.com or 800-463-6627 for more about our solutions.

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