FW: Summary: Documentation on Installation CDs

[Bevan McCabe <Bevan -at- SOFTTECH -dot- CO -dot- NZ>]

Hi,

I received some replies to my enquiry about what kind of documentation to
include with installations. If anyone has any further ideas, feel free to
continue this discussion.

Big thanks to everyone who responded :-)
Most responses said to separate the end user and database developer
information. The database developers should be able to access both sorts of
help, but the end users should only be able to access theirs. Unfortunately,
with our product there is no clear line between them, so this will be a bit
tricky to do. I need to do a bit more audience research before coming up
with a solution.

Here are the specific responses:
From: Ursula Ryan

Several of our applications require users to populate their databases, and
the developers approach it in three ways:

1)  Create a user interface for it (i.e. setting up "products" or
"materials" in the database) that is part of the main application.

2)  Create an import utility for existing data (i.e. financial forecasts,
employee timesheets, etc) that only administrators use

3)  Create stored procedures which the administrator runs to populate the
database with seed data.  (i.e. stuff you need to have in the database
before the application will work, such as User accounts)

In the first case, we include instructions with the main part of the
application, and indicate which users have security privileges for these
functions.  In the other two cases, we make information like this available
only in the Administrator's Guide (not the user guide), which includes an
"installation" instructions for the database, server, and client, and any
required hardware, and a "system architecture" chapter with a data model of
the database, an explanation of every table in the database, any stored
procedures or views we have created already.

We assume the user knows how to work with SQL databases, so we don't provide
basic material (like "Click Save to save" instructions).  However, we always
provide guidelines on the procedure ( like "you should first create product
groups by doing X, then create products, then create sub models of the
product" ).

Hope this helps.
Ursula

From: Mike Baker

        The company I work for has run into the same issues.  We have a
manual, printed and online, for the end user (advanced and beginning).
We also have a System Fundamentals guide for the database developers
that is sent separate and is only for the developers.  Currently we have
three sets of documentation as well.  We have the main Reference Guide
that is printed and online.  We have a System Fundamental Guide for the
developers, and we have a Tutorial that we run off the web.  The web
works very well for the tutorial since we are allowed to modify it as
necessary.  Plus with the information on the web we can better separate
tutorials for advanced users as well as beginners.

The software that we document is very specialized and instead of having
a getting started manual, we have a reference guide.  The guide is laid
out in a fashion that the advanced user can go directly to the
information they need, where as the beginning user goes through every
step.

We have received very good feed back on the way the information is
distributed.
All of our customers seem to like the way the manual is laid out.
I don't know if this helped at all.  What kind of software are you
documenting and what is your main audience?

Mike Baker
Technical Writer
Advanced Research Systems
mikeb -at- ar-systems -dot- com

From: Rebecca Siegel

We have a similar situation with one of our new products. Customer service
representatives at printing companies will use this Windows product to
produce job quotes by selecting information from a list of items. A few
people (maybe just one) at each site will create and maintain the item
lists.

We're trying to figure out how to structure the Help file so that each of
these two types of users can get the information they need. The first kind
of user needs to know how to use our product; the second kind needs that
information PLUS how to configure and maintain the item list. We've
considered creating two separate "books" within our Help file. We've also
considered creating two separate Help files (both accessible from the Help
menu).

-Rebecca Siegel
Tech Comm Team Leader
Logic Associates
rebecca -at- zlogic -dot- com

From: Patti Anastasia

The product I work on has 3 audiences: programmers who customize it,
administrators who manage it the database and the product, and end
users.

Originally, the admins and end users shared a UI, but permissions were
used to prevent end users from doing admin work. We recently split up
the UI so that there are separate UIs for admins and end users. But even
before the UI split, we separated the end user and admin help.

We create separate documentation for each of the audiences. Our doc set
has the following components:

Getting Started
End user help
Admin help
Customization guide
System admin guide

Everthing is HTML, mostly WebHelp, but some "pure" HTML.

The admin help actually consists of the end user help plus the admin
help. We've tried to make our information modular. Also we link the
documents. Since the admin and programmers sometimes need to understand
info in the end user help, we link from the admin and programmer  doc to
the end user help. We never link from the end user help to the admin or
programmer doc.

I think you're on the right track trying to separate the database
developer help from the end user help. There are plenty of options on
how to deliver the separated info. You could put it in a database
developers section or in separate documents. If the db developers need
some of the info in the end user help, you can put all of the common
info in a module that gets included in the end user doc and the db
developers doc.

Hope this helps,
Patti
____________
Patti Anastasia
Silknet Software, Inc.
The Gateway Building
50 Phillippe Cote Street
Manchester, NH 03101
603-625-0070
pattia -at- silknet -dot- com

From: Judith Blackbourn

I would ask these questions:
* How does the user access the help system?

If from context-sensitive link (e.g. help button or F1), the information the
user sees
first would be directly related to the screen being used. You could add a
button or link
called "Advanced" to give access to more advanced information.

If from the Help menu, you could organize your table of contents to group
topics by
user (database developers, end user).

Regardless of access point, you can use design elements to distinguish
information
intended for specific users. In my current project, we've developed an icon
to represent
each of our three user groups. Each help topic shows the representative icon
in the
non-scrolling region, to help identify appropriate information for that
particular
user. Also, browse sequences stay within topics for one user type.

* Is it possible that the end user will go to
the database developer for help with tasks?

Then you would want the developer to have access to the same help
information as the
end user, without having to launch a separate program.

And finally, for those who missed it, my original query:

(cross-posted to winhlp-l and techwr-l lists)
This question only relates to documentation for computer software
applications released with a database, which the users have to populate with
their own data.

Do you know of any web sites with information on this topic?
(I tried searching the archives, and a general search, but couldn't find
anything)
If you have time to spare, please answer the following questions. (They're
kind of involved.)

For our product, (software for window design), there are 2 audiences of
users. Firstly, the database developers (only a few at each company) who
will be entering their company's information into the database.
Secondly, the end users (lots at each company) who will be making quotes
using this information. These users will never need to alter database
information.

Would you have 2 sets of documentation, customized for each type of user?
Or, should the topics be included in a single help file, where each user is
less likely to run into advanced topics?
I think the instructions on how the database developers enter their data
should be obviously separate to the instructions for how the end users make
quotes etc.

Currently we have 3 sets of documentation.
1. a Getting Started manual, which is available printed or online.
2. a Tutorial, intended for advanced users, only available printed.
3. Online help, covering all features of the program, intended for basic and
advanced users.

I am not so much interested in the format ([pdf, hlp etc] though feel free
to include details of that), but rather the content of documentation - what
goes where.

Thanks again,
Bevan McCabe
Technical Writer
Soft Tech (NZ) Ltd.
Auckland, New Zealand.
Ph: +649 303-1113
mailto:bevan -at- softtech -dot- co -dot- nz