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.
> Howard Peirce is pondering <<...design considerations for
> very large hypertexts? By "very large," I mean roughly
> equivalent to ~10,000 printed pages.>>
>
> Youch! Glad I'm not the editor on that project.
I'll pass your sympathies on to Emily <g>.
> <<Our current documentation (shipped in HTML) uses a
> "library of books" navigational paradigm... the user chooses
> one of roughly 40 "books," and navigates primarily by means
> of a java-based hierarchical TOC.>>
>
> On the (inter)face of it, that sounds like a reasonable design,
> though I have to wonder (not knowing how you've separated
> your books) how intuitive this is.
In general, there are four basic applications, plus product-wide information,
and open architecture documentation. Each application in turn consists of
several tasks. Each task is a book (except when there are several tasks in
one book--don't ask). Books vary from ~50 - ~400 pages, depending on the
complexity of the task.
The problem is, the task are far from self-contained. There is some
hyperlinking across books, but often the only way to get around is to dig
your way up to the top and burrow back down.
And, the search function only works in one book at a time. Sometimes the
thing you're looking for is in another book, in which case you're hosed
unless you magically guess right the first time.
> I suspect that a large part of your reaction relates solely to the
> fact that you're too close to the project to be truly objective; I
> once spent several profitable but wearying days scanning a
> large database of addresses to identify missing and obviously
> incorrect information, as well as flagging anything suspicious
> that needed verification.
Well, actually, I'm pretty clear-headed when I do the QA work, because I do
that in portions of the documentation I wrote. When I have trouble is when
I'm using the documentation to learn about aspects of the software that I've
never worked with. So, I might write about Simulation, but need to learn
something about Design, so I go into the Design documentation like any other
user.
> In
> particular, what does your audience think?
Aye, there's the rub. We were on a proprietary system until recently. The
HTML version has only been out with the users for about 8 months. But we're
already two releases ahead of that in development. There's yet to be a lot of
feedback generated, and the usability testing has been mixed.
> Despite what I've said, there's almost certainly some validity
> to the problem you've identified. I've occasionally seen
> people use different visual coding schemes (e.g., different
> paper colors or different graphic ornaments in the running
> header for different manuals) so that readers know when
> they've changed modules.
Yes, we change banner headings for the different books. The design is the
same, but the color and text change (and, we writers had to fight even for
this; the production group didn't want it). But, since the software runs on
multiple platforms with various video drivers, I find the colors come up
inconsistently anyway.
> I've also tried some of these
> tricks and discovered afterwards that my graphics colleagues
> and I were the only ones who ever noticed them.
That doesn't surprise me. I think the theory is that these things operate at
a preconsious level. The real test would be a double-blind study, where one
set has visual cues built in and the other doesn't.
> Variety for its own sake is rarely useful, but I think you've hit
> the important point here: different types of information
> require different formatting. <snip exmples> So if two different types of
> information look identical, you're doing your audience a
> disservice. In this case, the "cues" are less important for their
> own sake; they're more a symptom of whether the format of
> the information really supports its use.
I agree, but what level of granularity determines "different types of
information"? You're examples are fairly fine: tables vs. numbered lists vs.
front matter. But what about larger categories of information? For example,
one procedure might involve the general steps in taking a mechanical design
from a crude sketch to complex part to drafting to simulation to writing
control programs for NC machining. Another procedure might involve the
sequence of selecting options for a single modal form. These are both
procedures, but very different kinds of information. Right now they're not
distinguished. Also, our users range from kids with associate degrees to
engineering Ph.Ds to managers with MBAs. I think consistency should take a
back seat to targeting these specific audiences.
> <<the WWW itself becomes a navigational paradigm--I never
> get lost when websurfing, because each site is unique.>>
>
> Unfortunately, you may be an exception to the general rule,
> though I've read conflicting reports on the frequency of
> "getting lost in cyberspace"; even if you're not atypical, your
> example is misleading.
Well, that is an issue. I've tended to spend my whole life at the narrow end
of the bell curve, so I'm never sure how my instincts translate into the
"typical user." I'm also pretty darn sure that the software I'm currently
documenting has no typical user.
> For example, <snip example> That suggests that
> variety may only be important at the micro level
> (differentiating two types of information, not two books).
You may be right. But again, what is the standard for differentiating
different types of information? Another example: Some procedures are
absolutely basic, and all users need to understand and feel comfortable with
them to use them every day. Other procedures are used only rarely, by highly
skilled users, and only in exceptional situations. Do these constitute
different "types" of information?
I believe that in many cases, the different books in our documentation set
are themselves different types of information.
> <<how easily would you navigate the Web if all sites looked
> alike?)>>
>
> Personally, I'd do just fine with that, but I'm a very text-
> centered person; I am visually skilled too, but I have to
> consciously switch modes of perception (the robot said <g>)
> to become "fully functional" in the other medium.
Me, too--assuming I'm reading. In a very large documentation set, however,
users are more likely to be browsing, looking for a particular piece of
information. And I do know that my users tend to be graphical rather than
text-oriented--more likely to stop for a table or a diagram than for text.
> Other
> audiences would respond differently, and it pays to remember
> that.
Exactly. Which is why I'm looking for research, and not trying to invent a
solution out of thin air.
