TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
On Mar 24, Leonor Ciarlone <lciarlone -at- NORWOOD -dot- INTELLUTION -dot- COM> wrote:
> Subject: PDF, SGML, and what else?
> (Opening the
> can of worms as to the difference between "online help" and
> "online documentation").
Can I open the can? ;-)
I'm in the process of writing online docs/context sensitive help right now,
and I'm curious what other tech-whirlers think about structuring such
information.
My initial approach to this problem is as follows:
Our software can be divided into "modules", and I'm writing a manual
on each module. The manuals are structured like this:
1) What is this module? When should I use it?
2) Short tutorial for those too impatient to read the whole manual
3) Basic concepts the user needs to understand in order to make sense of
the reference material
4) Reference material
The first three sections are meant to be read by someone new to the
software. They're not reference material -- they should be read more
or less cover-to-cover. The fourth section is meant to be context
sensitive. That is, it's a task oriented description of how to use
each icon in the GUI; for example, "How to do xyz using the abc icon".
Section 4 would be heavily hyperlinked to section 3, so that users
too impatient to read the "basic concepts" section can easily refer
to it when they run into things they don't understand in the reference
material.
I'd like to issue all these manuals both in print and as online books.
The context senstivity software would then hyperlink into the right
place in Section 4, and would present the user with ONLY the section
of current interest. The user is free to push a button that brings
up the entire book, opened to the right "page", for further reading.
Does this approach make sense? How have you folks tackled this problem?
--
Glenda Jeffrey Email: jeffrey -at- hks -dot- com
Hibbitt, Karlsson & Sorensen, Inc Phone: 401-727-4200
1080 Main St. Fax: 401-727-4208
Pawtucket, RI 02860
