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: TW and grad school -Reply From:Michael Lewis <lewism -at- BRANDLE -dot- COM -dot- AU> Date:Fri, 13 Feb 1998 11:38:22 +1100
Even more good points, Linda!
Linda K. Sherman wrote:
> I intended to include organization and navigational issues by using the
> term "format"--poor choice of words on my part. I agree that
> organization and navigation are the main issues; that was actually what
> I was trying to say.
> > I have never accepted the argument that printed text is "linear".
> Well sometimes it is. Novels, for example. More relevant examples are
> training materials, tutorials, and procedural instructions. These may
> not be entirely linear ("If your computer doesn't have a CD-ROM drive,
> skip to step 27"), but overall they tend to be and are usually meant to
> be used in that fashion. If anything, this is an argument for putting
> them online--it's very hard to stop a use from jumping around in a
> hardcopy manual.
I concede that the content of some books is indeed linear. Here I
confess to my own poor choice of words: I should have said "_inherently_
linear". A novel is not expected to provide much in the way of
navigational information. A historical account of some sort might also
be primarily for linear reading, but there will also be an index for
navigation to specific points. And so on. But technical material -- and
not only "help"-type material -- can take advantage of the physical
nature of a book, plus the logical nature of headings, ToC, and index,
to provide navigational facilities that are equivalent to, albeit slower
and more cumbersome than, those available online.
> ... The advantage of having a hardcopy
> manual in front of you is that you can see the screen image and the
> documentation at the same time. Very few workers have terminals
> sufficiently large that they can open a documenation or help window
> beside their main work window without at least some overlap of the
> windows and resulting loss of visible information. This can be a
> problem, especially if you're trying to duplicate in your main window
> what you're reading in your doc/help window. Cut and paste helps (if
> available) in situations where you're copying text, but if you're, say,
> entering data into formatted fields in a data entry window, chances are
> pretty slim that you'd want to enter the data given in the doc/help
> example. The bottom line is that I have more room on my desk for books
> than for a second terminal!
True. However, pop-up windows of context-sensitive help can achieve the
same end at a lower cost in screen real estate. Once again, we are
talking about choosing features or facilities that are most appropriate
in the circumstances.
> Hardcopy "systems" can often be radically improved by judicious use of
> those little stick-on tab things to mark FUPs (frequently used pages). I
> must also point out that very few online help/documentation systems
> allow the user to add their own notes, and those that do rarely allow
> the user to put their notes just any old where in the text. With
> hardcopy, you can scribble in all the notes you want, right where you
> need them most. My programming reference manuals tend to be extremely
> marked up.
This is a really useful point. (Is "FUP" copyright, or can I use it?)
Interestingly, though, I've never been one for writing in books: I've
always used separate notebooks. That means I keep the notes even if the
book gets replaced with a version upgrade. Of course, annotations in
help systems (if supported) will also disappear at upgrade time, but
again I think that's an argument for a separate notebook.
> I think another reason people don't like hardcopy documentation is
> because the type of binding often fails to consider that the book is
> going to be laid open flat on a crowded desk. High-quality wire spiral
> bindings that allow you to fold the book back on itself are the best,
> and yet hardly anyone uses them.
Indeed. There's also a kind of ring binder that has a horizontal crease
across the entire cover, so that it can be propped up like an easel.
Expensive, of course, and probably most useful for training materials
rather than reference books.
> The usefulness of online documentation and help will vary considerably
> from one situation to the next, of course, as well as from one user to
> the next. I don't think it's possible to generalize accurately or
> fairly, and I would certainly recommend consulting with the end users if
> at all possible. Most commercial software manufacturers don't ask, but
> frankly, I don't think they want to know. Their documenation policies
> are driven by cost and marketing factors, and by inertial investment in
> existing documentation, not by user preferences.
Too true. For example, Microstuff claims to run usability tests on its
software, but they don't say much about their documentation. And, of
course, some of the most useful documentation for MS products is sold
separately -- and often by someone other than MS!
> ... very often I don't know what I'm looking
> for, or I want to browse for "goodies". This is easier to do with paper
> manuals, in my experience. The World Wide Web is a good example. If you
> know where you're going and/or exactly what you're looking for, it's
> relatively fast and simple. But if you're not so certain, the Web is a
> prime example of how not to do this kind of browsing. It's slow, you can
> get throughly lost trying to follow links, and it takes a lot of skill,
> ingenuity, and patience to use search engines.
A compelling argument. Book readers are immune to the "lost in
hyperspace" disease. However, let's compare apples with oranges rather
than with alligators. Unlike many web sites, a well-constructed online
document or help system will provide minimal opportunities for the user
to go off into other documents or systems. With a ToC and an index, an
online system can also be quite easy to search. But I think the biggest
argument in favour of books is that they are so deeply implanted in our
culture. You don't have to be a bibliophile to feel comfortable handling
a paper manual. Whether you feel comfortable with the content is another
> *** DYSGWCH YR IAITH GYMRAEG *** LEARN THE WELSH LANGUAGE ***
I plan to. Do you teach it?
Brandle Pty Limited, Sydney, Australia
PO Box 1249, Strawberry Hills, NSW 2012
Suite 8, The Watertower, 1 Marian St, Redfern 2016 http://www.brandle.com.au/~lewism
Tel +61-2-9310-2224 ... Fax +61-2-9310-5056