RE: advice for single-sourcing ( Framemaker + Webworks)

Subject: RE: advice for single-sourcing ( Framemaker + Webworks)
From: "Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 12 Jun 2001 11:52:29 -0600

Hi Sean,

You give sound advice from which a newbie can benefit. I mildly disagree
with just a few points. Not a big deal, but the discussion might be

You recommend shortening topics so they fit on-screen and being less
verbose. If the online help is WinHelp and if the topic is a pop-up, I
can't really fault this advice. However, recent usability findings (on
Websites) by Jared Spool and his UIE crew discovered that users aren't
so adverse to scrolling as previously supposed, particularly if the
information is useful. It is sort of counter-intuitive to the way
WinHelp has been designed over the years.

There are certainly camps that say online help (that is, application
documentation that is closely tied to the associated software) is
different than a website. I do not completely subscribe to this
philosophy, and neither does UIE. Yes, sometimes the availability of
tools (like server-side applications) and delivery mechanisms (CD versus
Internet) differ. I believe that online help (HLP/HTML) is closely
related to websites in its goals and techniques, and that good practices
in one environment carry over to the other.

I recently single-sourced some installation procedures and built them
into a larger help system (standard HTML). [I'll save for other postings
the reasons for putting the installation procedures in multiple formats
on the documentation CD in HTML and PDF.] I chunked the material into
chapters. The chapters didn't really lend themselves into further
chunking other than clearly defined steps. The steps by themselves would
have been poor on their own as free-standing topics, because they were
so short and had no real context except being a step relative to other
steps. I turned the individual chapters each into big HTML topics. The
scrolling isn't bad; you always know where you are in the procedure; you
can print out one single topic and have everything associated with that
larger procedure (chapter).

Another point about large topics. You should write what needs to be
said. Contrary to the beliefs of reactionaries and paranoid SMEs worried
about users shooting themselves in the foot, lots information -- within
limits, of course -- is less likely to hinder a user as much as too
little. The far greater majority of users are adept at scanning and
separating the wheat from the chaf. They would rather have the
information at their disposal so they can decide what to do rather than
have us writers cut out important tips and explanations just to fulfill
some arbitrary and invalid notion about small topics and no scrolling.
(Sometimes explaining what the user shouldn't do and why provides
insight into the application and our recommendations of what they should
do and why.)

Cutting out words and sentences isn't going to make the footprint on the
CD significantly smaller or the download time significantly shorter,
either. We're talking tiny electronic bytes here. (The computer's file
system already has minimum file size chunks anyway. When was the last
time you ever saw a file of, say, 100 Bytes? Everything is in 1 KB or 2
KB increments whether needed or not.)

Sean also recommends creating cross-references of the next lower-level
headings for a section. This is certainly valuable at the top levels. I
just advise caution about doing this at every level. Do it only when
really needed. It can quickly become a hard-to-maintain bell-and-whistle
that IMHO distracts the writer from fleshing out content and the reader
from finding content. Also IMHO, if time is limited and you have to
choose between features to implement, I would recommend focusing on the
table of contents and browse buttons.

I believe that being able to see, say, in a navigation pane an
expandable/collapsable TOC goes a long way into giving the user
understanding of the scope of the documentation/product, where they are,
where they need to go, and what they can explore in the future. Between
the TOC and the index, the user can get to the sections of interest.
Once there, page-forward/page-backward buttons (at the top and bottom of
each topic) facilitate learning the material in a linear way like it was
written and intended by the writer.

Too often the cross-references/hyperlinks from level n to all of its n+1
levels can cause the reader to jump over and completely miss important
points that they would have easily seen thumbing through a paper version
or paging forward/backward through an online version. Moreover, a good
TOC in a navigation pane lessons the need for such "level n to level
n+1" cross-references.

Book, chapter, and section can and should continue to have meaning in
the online world. Why re-invent the wheel? And why do online systems use
the little open/closed book icons? Don't go throwing the baby out with
the bath water.

If you are truly single-sourcing by providing not just online help but
also a printed and/or PDF version of the book, then it is beneficial to
retain precisely this nomenclature if for no other reason than to give
the users a warm-fuzzy feeling that the contents of the various output
formats are the same. The book/chapter/section concepts are already
familiar to the user.

In the system that I just created, I added a "This PDF" button to every
HTML topic and it hyperlinks to the owning PDF file for that topic. (I
don't and probably won't hyperlink from a topic to the exact same page
in the PDF.) HTML is great for hyperlinking around, but isn't printer
friendly. The PDF, on the other hand, is laid out for print and permits
printing of ranges of pages.

I PURPOSELY left cross-references that refer to PAGE NUMBERS. I even
include FrameMaker TOC and Index files as part of what is exported to
HTML, both with working hyperlinks.

(1) The page references tie the online version to the PDF/print

(2) Users don't care one way or another about whether or not hyperlinks
contain references to pages or say "chapter such-and-such on page nn",
"Figure x.y entitled 'blah-bleh-bluh' on page nn", etc.
[a] IF the hyperlink text provides enough information about where it
takes the user AND
[b] IF the hyperlink works.

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: Brierley, Sean [mailto:Sean -at- Quodata -dot- Com]
> Sent: Tuesday, June 12, 2001 8:11 AM
> Subject: RE: advice for single-sourcing ( Framemaker + Webworks)

> For example, I recommend you make extensive use of
> cross-references. Do not create dead-end topics, ones to which a
person can navigate
> in the online help and then get stuck with nowhere to go.

> My headings have a cross-reference list of next lower-heading levels
in the
> section, such that a Heading2 would have a cross-reference to all the
> in its section.

> Never follow a heading with another heading. This works in
> printed docs but
> not online, where it results in blank topics. Consider using
> conditional
> text to set up online and print conditions. Consider tagging
> the anchored
> frames of superfluous screen captures and graphics with the
> print condition
> so they stay out of the online help where they are less
> useful.

> Shorten your topics so they fit on-screen; consider being less

> Make a thorough
> index. Carefully consider your vocabulary. Book, chapter,
> page, and the like
> fail to have meaning in online help. However, remember you can take
> advantage of the linear layout of printed materials. An online help
> publication can be linear even though it does not have to be
> navigated in linear fashion.


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

Sponsored by Cub Lea, specialist in low-cost outsourced development
and documentation. Overload and time-sensitive jobs at exceptional
rates. Unique free gifts for all visitors to

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.

Previous by Author: RE: global replace with RoboHelp?
Next by Author: RE: department software restructuring
Previous by Thread: RE: advice for single-sourcing ( Framemaker + Webworks)
Next by Thread: RE: advice for single-sourcing ( Framemaker + Webworks)

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

Sponsored Ads