RE: User Manual and Online Help

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

Hi Sarika,

I think you might be making a bigger deal about what images are appropriate
in the manual and what are appropriate in online help.

I'm a radical and say "put them in both places."

What we forget is that readers are very good at skimming and moving over
material that they don't need -- if indeed the images aren't needed.

However, IMHO I believe that the same images from a printed manual are
needed in online help (in nearly all cases). I am aware that many times the
user clicks on a help button from a dialog box and *POOF* there's the online
documentation topic relating to that dialog box. Hence, it *might* be
redundant to then show an image of the same dialog box. I say it's not.

First of all, the image serves to give the reader a fuzzy warm feeling that
"yes indeed, this topic does talk about exactly the same dialog box that I
see in the software." They will quickly scroll passed it and read your text.
It may bother you as a writer, but it doesn't bother the reader.

Bare in mind that with all of the hyperlinking that goes on with online
help, many times users will land on that topic FROM SOMEWHERE ELSE other
than from the help button in the dialog box. They can get to it from the
TOC, multiple places in the index, lots of other topics, and browsing.
Hence, the image re-enforces what the text talks about.

Moreover, if they did get to that important topic from some other place like
the index, the image tells them HOW TO GET TO THE FUNCTIONALITY in the
software... or at least what they need to look for to get to that
functionality.

I don't know what the images are that you say are in the manual and don't
belong in help. Yet, my gut feeling is that they probably are needed and at
worst, won't hurt anything if they do appear in online help.

As far as that goes and more reflection on my radical nature, I also take
the position that even the text in most cases does not need to be tweaked
from a print manual to an online help system.

If the text says "Refer to Figure 3-12 on page 3-27", so what? True, there
are no "pages" in online help and the distinction between chapters might not
clearly exist. However, you probably implemented it as a cross-reference in
your documentation software. The conversion software to get this into
HTML -- if it is worth its salt -- probably automatically converted that
into an accurate hyperlink. As long as the hyperlink works in online help,
READERS AREN'T GOING TO CARE whether it says "page 8-3" or "click on me".

In my last project, I single-sourced from FrameMaker into PDF (for print)
and an HTML online system. I had tools that post-processed the HTML files to
add navigation and copyright stuff. One of the things that they added was a
"This PDF" button. In other words, any given HTML topic knew the PDF file
that was associated with it. The benefit of this is that PDF allows more
control over printing than the browser. The reader could print out a range
of pages or the whole manual from the PDF and get results that are laid-out
and designed for print.

At any rate, I purposely left in all references to chapters and page
numbers. I wanted the reader to know and see how the online help related to
the printed manual.

In conclusion, customizing a document that was originally intended for print
so that it seems more logical in online help is probably wasted effort when
you consider the marginal gains to the reader. Readers aren't going to care
if they see extra images in online help or paper-specific references as long
as the information is relevant and the cross-references (hyperlinks) work.

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com


> -----Original Message-----
> From: bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com]On Behalf Of
> sarika -at- infozech -dot- com
> Sent: Friday, May 04, 2001 3:36 AM
> To: TECHWR-L
> Subject: User Manual and Online Help
>
>
> Hi All,
> I have to implement Robo HTML Help in our Software.
> I want to avoid duplicity of work. Although I know I can import a Word doc
> and convert it into help file, but the problem is I don?t need screens in
> Help file which is otherwise included in the Manual. If I choose to remove
> the screens, I will have to change the language flow of the entire Help
> File.
> Is there any other way of managing both of them or what would be the ideal
> thing to do in such a situation.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See
http://www.infomap.com or 800-463-6627 for more about our solutions.

---
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.