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: Moving Documents from Hard Copy to Online From:Alfred Barten <barten -at- ORRQMS2 -dot- GDDS -dot- COM> Date:Tue, 20 Apr 1999 10:24:01 -0400
At 07:09 AM 4/19/99 -0600, ddavis wrote:
>Has anyone recently restructured a hard-copy book or a set of books for
>online delivery? Did you re-format and re-organize of the documents as a
>result? How did you make your decisions about why and how to make the
I've converted several paper manuals to online and created several other
online manuals from scratch. This has been the mainstay of my work over the
last five years (some of these are BIG projects). From the start I began
with the conviction that the optimimum online manual is fundamentally (read
structurally) different from the optimum paper manual. This becomes
critical when your online manual needs to be context-sensitive at the
screen level - which all of mine are. You suddenly are confronted with
questions such as Where am I? How did I get here? What does what I'm
looking at have to do with anything else?
Another thing to consider is what the user expects from your manual. Based
on my own experience, I assume the user is entering the help system in
order to find an answer to a specific question, such as What happens when I
select option A? or What is the significance of the data in field XXX? I
also assume the user may actually want some descriptive information or an
overview, though probably not as a first requirement.
Last summer I wrote a series of four articles for the Boston Broadside, the
newsletter for the Boston Chapter of the Society for Terchnical
Communication. The first was published in the November-December 1998 issue
and entitled Thinking From Within the Box: An approach to designing online
documents. This first article summarized my appraoch, which is to imagine
myself within the document, moving around as though in Calvin's
cardboard-box-turned time machine, exploring the ages. Like any good
vehicle, Calvin's box should be equipped with windows, instruments, and
controls to let him see where he's going, collect information about his
position, and control his next move. This is not unlike driving through an
unfamiliar landscape with nothing to guide you but a road map and raodsigns
along the way. In both analogies you have destinations where you can find
things you need or are looking for. A town, for example, has a store, a
school, a gas station, etc. - similar to the ones in the next town, yet
To put this into the context of an online manual, I structure my manual as
a series of Information Centers surrounded by arrays of information -
analagous to my vehicle's cockpit. In the manuals I've been creating, an
Information Center is a point of entry and also represents a screen in the
software I'm documenting. This center provides direct access to pop-up info
on all fields, buttons, options, and pop-up menus for that screen. It also
provides direct access to instructions. Buttons take you to local/regional
overviews and instructions. One button takes you Home - yes, I'm now using
Home in my online manuals. Home used to be Introduction, but who ever looks
at the introduction? Web users know the value of Home.
I set forth a number of goals when I start an online manual, but two
reminders are noteworthy here: 1) An electronic manual should be organized
as centers surrounded by arrays of information, and 2) you should provide
direct or unambiguous near-direct access to all information (i.e., don't
expect a user to dig very deeply).
I'm planning a web page to present all of this in greater detail, but it
may be a month or so before it's officially launched.
I hope this is useful. If you or anyone esle wants to talk further offline,
write me at abarten -at- crocker -dot- com -dot-
>From ??? -at- ??? Sun Jan 00 00:00:00 0000==