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

["Rebecca Downey" <rdowney -at- matrox -dot- com>]

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 http://www.ehelp.com/techwr-l

  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 http://www.raycomm.com/techwhirl/ for more resources and info.