RE: On-line vs. print (WAS: Of myth and reality)?

Subject: RE: On-line vs. print (WAS: Of myth and reality)?
From: "Rebecca Downey" <rdowney -at- matrox -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 1 Aug 2002 14:02:55 -0400

Good afternoon.

> Well, this subject certainly didn't garner much interest did it?
I was hoping for a reply as well - specifically from someone who believes
there is a difference between on-line and print.

> is there nobody willing to discuss the requirements of on-line
> documentation?
I can, and will - but my belief is that requirements for good documentation
are the same, regardless of their final output.

> How can the user be kept
> 'in context' when drilling around in on-line documentation?

* The first is the use of a navigation bar.
I use HTML Help, not WinHelp; so my limitations as to design and function
are the same limitations as in a HTML file. In every topic (Heading 2s) I
have a navigation bar directly below the header that lists:

Chapter Name > Heading 1 > Heading 2

At the end of each topic I have a detailed list of related topics, broken
down by:
Window, Task, Error and log Messages.

* The second is the use of cross-links.
When generating a cross-link, I try to keep the name of the item to which
I'm linking together. Sometimes this means adding words to the link (for
example: the X window, the task's title, the Z error message). Sometimes
this means changing the link entirely to something that provides the
context. Refer to "X window", "this option" instead of just "this option".

> Or, in printed documentation how do you best present detailed
> information yet still allow the user to quickly find procedural
> instructions that don't assume they've read the whole book?

The best way I've found is to list other related topics at the end of the
topic under discussion.

Everything I write now goes on line in either HTML or PDF. All the documents
for the same product are indexed on pages over which I have no control. When
I have to cross-link from one document (say a FAQ) to another (say a
Tutorial), I make the link based on the current state of the web page and
notify the web-folk where the cross-link occurs.

I began technical writing 5 years ago with solely-printed documentation. Now
I'm solely-online. The change has not been that dramatic. I have found the
most-preferred online help systems are well-designed documents that require
only formatting changes to go from print to online.

Print may have the ability to contain long-winded passages (certainly it's
more acceptable there than online), but that does not endear your print
documents to your reader. Writing for online (using short sentences, clear
points, etc) is just an oversimplification of the KISS statement. (Keep it
Simple and Short, or Keep it Simple Stupid). I prefer: Clear, Concise and
Consistent. :)

Rebecca Downey Senior Technical Writer
ITG:NBM Matrox Electronic System
1055 St Regis, Dorval, Quebec, H9P 2T4

Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Re: On-line vs. print (WAS: Of myth and reality)?: From: eric . dunn

Previous by Author: RE: Visio and File Size...
Next by Author: RE: On-Line Vs. Print, Single-Sourcing, and how to ignore the obvious
Previous by Thread: Re: On-line vs. print (WAS: Of myth and reality)?
Next by Thread: RE: On-line vs. print (WAS: Of myth and reality)?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads