Re: Online help and the elimination of the printed doc

["Chuck Martin" <cm -at- writeforyou -dot- com>]

<Daniel_Hall -at- trendmicro -dot- com> wrote in message news:225479 -at- techwr-l -dot-  -dot-  -dot- 

I am presently pondering the possibility of purging the "printed"
documentation from a product I'm documenting. (Like that alliteration? It's
Friday!) Actually, we would still provide a smallish printed document,
containing "Getting Started" info, as well as troubleshooting (the two times
you're not likely to have access to the online help).

Background:
This is a server-based gateway security product that resides in the DMZ and
is accessed remotely through a Web UI.

Proposal:
I am proposing a significant reduction in the printed documentation, coupled
to incorporating a significant increase in the volume and detail of the
online help. The current online help is mostly a re-hash of the info from
the printed doc, useful, but... yuck.

We would provide per-screen help that would offer comprehensive information
on the tasks for that screen, as well as providing access to a TOC, index,
and search functionality. We have recently implemented a new UI standard, so
I would also provide control-level help - a succinct explanation of each
control's purpose along with the valid values, etc. I would also undertake
to thoroughly annotate the configuration files.

Question:
Has anyone else worked on a product providing help at this level of detail?
Any suggestions, comments, or warnings?

My main concern is that there is a good deal of conceptual information that
the user must understand in order to be able to use the product as part of a
comprehensive security plan, and it just doesn't seem appropriate to put
this material into the help. I've always been an advocate of relegating that
type of info to the printed docs, and keeping the help focused on task-based
instructions.

Dan

_______________________________________________


First of all, there's nothing inherently wrong with putting conceptual
information online. In fact, its entirely useful to make conceptual
information an integral part of online content, in most

cases layering the conceptual information so it doesn't obscure the
procedural information but is easily available should users need  more
information to make decisions during the procedures.

If you're woring within a web-based application, I'd strongly push for more
embedded content and content that is quickly available without opeining up a
separate help system window. Embedded content within the pages of the web
application provides just-in-time information to assist users in making
decisions for each field and control. Quickly available content would mean
adding to the design a small icon or link that creates a small pop-up with
further clarifying information. (This is usually most easily done with
JavaScripting.)

This also requires working with the design and programming team to lay out
the user interface not only so it makes sense to users and inherenly helps
them reach their goals, but to make space for the performance assistance
text and to program the added layers of information. Especially on a control
level, this is far, far better than opening up a separate help system, sort
of like What's This? Help in Windows applications.

When you say "DMZ," are you talking about the application being used in the
military or in areas where the military holds sway? If so, then almost
anything printed beyond the bare minimum I'd think would be less than
desired. Unless users are in a safe haven where books can be stored, the
less users have to carry with them, I'd assume the better.

But then, how much is the "new UI standard" self-documenting--and if it
isn't (ir isn't very well), then what was the point of a new UI effort? It's
incredibly important to have web-based applications be as self-documenting
as possible. Print manuals are so much less useful when your product can be
accessed from just about anywhere.

Finally--and you probably already know this--a "rehash" of the printed docs,
no matter how well the information in the printed docs is designed, probably
isn't going be be an effective design of information for online
presentation. (No resourxes to redesign the information? Then how could you
afford resources to do a UI design? They are not unrelated.)

At most, I'd probably want to offer a small-format quick-start type guide
that highlights where to go inthe application to perform most common tasks,
something no larger than a page or two, easily pocketable and lightweight.
(But then, I'm making some assumptions about user characteristices. Creating
a user persona or two can help drive documentation design decisions as well
as it does in driving product design decisions.)


-- 
--
Chuck Martin
User Assistance & Experience Engineer
twriter "at" sonic "dot" net      www.writeforyou.com

"I see in your eyes the same fear that would take the heart of me. The day
may come when the courage of Men fail,  when we forsake our friends and
break all bonds of fellowship. But it is not this day! This day, we fight!"
                    - Aragorn

"All you have to decide is what to do with the time that is given you."
                    - Gandalf