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.
Subject:Re: Navigational paradigms, take II From:Howard Peirce <howard -dot- peirce -at- SDRC -dot- COM> Date:Mon, 10 May 1999 14:55:19 -0400
Thanks for challenging me on every point <g>. You've given me much to think
about. Just a few points.
Geoff Hart wrote:
> Sounds like this is a good candidate for diverging from the
> (paper) book model
Absolutely. But a lot of the decision-makers are absolutely commited to the
paper book model, and I need some incontrovertible evidence to the contrary
to sway them.
> repeat certain necessary information in each book rather than
> insisting on hyperlinks. (There are various ways to do this
> without spawning several different and incompatible versions
> of the repeated text.)
Repetition is big issue, considering the total amount of information, and the
localization costs involved. I'm no SGML expert, but isn't it possible to use
content tags and chunk information, so it's stored in one place, but
referenced in several?
> <<There's yet to be a lot of feedback generated, and the
> usability testing has been mixed.>>
> Fortunately, you're publishing HTML; it's easy to update.
Not with our current system. Again--it's a mess; don't ask. Let's just say it
involves a string of t 3rd party conversion codes cobbled together inhouse.
Once we go to native HTML (ideally SGML) authoring, though, you'll be
> What differs most among users is the amount and nature of
> the information they need, not how you express that
> information. (Using the jargon doesn't necessarily improve
> communication, other than for predominantly specialized
> audiences.) The problem then becomes one of formatting
> (i.e., how to keep all the information easily available, without
> burying expert users in info they don't need).
Here's the real crux of the problem. We have no way of distinguishing basic
from advanced information--the UI doesn't make that distinction either,
unfortunately. And I'm less worried about burying expert users in elementary
information, as I am about burying the elementary user in a pile of caveats
and detailed explanations of switches they'll never use.
> <<But again, what is the standard for differentiating
> different types of information?>>
> The more complex
> you make your differentiation, the more complex you make
> the task of understanding that coding.
Again, I agree--this is my philosophy as well. Perhaps you misunderstand my
point about variety. It's not about establishing a design schema to be
implemented product wide. It's more about recognizing that each "book" is
unique--it has it's own audience, it's own level of technical difficulty.
When I worked in trade computer book publishing, each imprint and each series
might do a book about the same application. Compare an Alpha Books "Idiot's
Guide to MS Word" book to a Que "Using MS Word" book to a Sams book on
developing third-party apps for MS Word. Each book has its own radically
different look and feel, to target a specific segment of the market. And
there's actually quite little repetition.
By analogy, our inhouse documentation set is like an encyclopedia. Perhaps we
need to look at our user base as a set of markets. Produce a "shelf of books"
much like the shelf of third-party books already sitting next to most users'
workstations, rather than the encyclopedic collection of giant black ring
binders like most high-end companies produced before going online. We already
have that to a certain extent--the tutorials and CBT look and work
differently from the online help, and nobody seems to mind. (In fact,
tutorials and CBT are among our most popular documentation products.) I would
just like to break it down further.
> However, I would say that you need to be sure that you've
> analyzed your users correctly; if you have, the general user
> probably shouldn't have access to the complex information in
> the first place: either they can't use it (e.g., lack security
> clearance) or shouldn't try to use it.
Again, this is an issue I have with both the decision makers in documentation
and in product development. Right now, 90% of our users use 10% of the
product. But nobody knows how it breaks down, nor do they seem particularly
interested in finding out.
Finally, with SGML, CGI, Java, and other tools, to what extent is it possible
to build intelligence into a browser-based help system? For example, I would
like to be able to ask the user questions (through a form) about exactly what
task they're trying to perform, and build a procedure on the fly from their
answers to the questions. A big part of my problem is that the software
itself has a lot of flexibility built into it, but the documentation format
is rigidly linear. But an intelligent system, that knows (or can be told)
what the user is doing, could eliminate a lot of ambiguity. Sort of a virtual
"co-worker in the next cubicle."