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.
Re: Digest of cross-reference on-line strategy information
Subject:Re: Digest of cross-reference on-line strategy information From:"Brown, Judi" <JHB -at- BTV -dot- MSMAIL -dot- IDX -dot- COM> Date:Fri, 1 Nov 1996 10:47:00 EST
Thought some of this might help you. It's from the Tech Writers' mailing
If you want to subscribe to this mailing list, let me know. I'll send
you info on how to do that.
From: TECHWR-L[SMTP:TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU]
Sent: Friday, November 01, 1996 9:45 AM
Subject: Digest of cross-reference on-line strategy information
About a week ago, I posted a message asking for recommendations for
on-line documentation platforms for a cross-platform implementation. I
asked people to respond to me and I'd put out a summary. So here it is:
I considered the following options:
-- Adobe Acrobat (www.frame.com)
-- Frame Viewer and Frame Reader
-- GUIDE Publishing
The most salient feature of the software I'm documenting is that it's
written in Java and can run on almost any platform. The documentation
also has to run on almost any platform. We're starting with Windows and
UNIX, but I added VMS because that seems like a logical platform we
might wind up supporting.
The winner is HTML, but we'll have to come up with a search engine
written in Java (for use on multiple platforms). The main reason is that
HTML seems to have the widest possible array of supported platforms and
the simplest implementation.
I've included the text of a message posted by Ian Spira, which gave me
some leads to follow up. Hope this is useful.
Thanks for your input.
On Oct. 17 I asked about tools for creating online documents. Here is a
of the messages I've received.
Samantha suggested a product called Envoy, by Tumbleweed Corporation.
using it to convert all of our documentation to an online format, and
(brief) experience with it has been positive. One of Envoy's best
that it can be read across almost any platform."
I had a look at Tumbleweed's web pages. It appears that Envoy is similar
least in concept) to Adobe Acrobat: you print out your file and convert
postscript file to Envoy format. All formatting, fonts, etc. are
viewer is free, but the other tools aren't. Here's a brief summary of
Tumbleweed's offerings. I lifted this from their web page:
Tumbleweed Software offers the following products for electronic
based on the Envoy portable document technology.
Envoy 7 with Tumbleweed Extensions -- Publish any document in Envoy by
printing! Tumbleweed Extensions offer enhanced features. (Special: $49)
Tumbleweed Publisher -- Convert your PostScript, EPS, and PDF files
into Envoy documents with a click of a button. Supports batch
Tumbleweed Envoy OCX -- Create or embed in your application a customized
Tumbleweed Publishing Essentials -- Suite of publishing tools provides
tools available to publish and organize large collections of Envoy
Envoy 7 Software Developer's Kit -- Build your own customized Envoy
Envoy Viewer -- View and annotate Envoy portable documents! (Free)
Envoy Plug-in for Netscape Navigator 2.0 -- View Envoy documents posted
Internet right inside your Netscape browser!(Free)
David suggested that I reconsider Acrobat as "it sounds like it would
about 90% of your requirements."
"Acrobat does a lot more than turn pages...it has the search
hyperlinking, multiple platforms, etc. If you're basing the decision on
what you've seen put into PDF format in the past, check out Adobe's web
site to see what's changed."
Two of my requirements were that the viewer work on multiple platforms &
complex tables. John pointed out that these requirements ruled out
However, John noted that a third requirement (that the viewer support
indexes) "doesn't eliminate WinHelp. Many people mistakenly believe
features are not supported in WinHelp, and this is partially correct.
no explicitly built-in TOC or index support, but there is NO REASON why
author can't create these just like you do for a printed manual and put
the online version. Hyperlinking the index and TOC using any WinHelp
be tedious, but it is POSSIBLE."
John also recommended FrameMaker, FrameViewer and FrameReader:
I think the only product that will meet the majority of your needs is
and its online companions of FrameViewer and FrameReader. It is
(it handles ALL the platforms you listed plus many more), it is built to
large documents (unlike MS Word and WinHelp), it handles complex tables,
spot graphics, TOCs , indexes (it will even build hypertext linked TOCs
indexes for you automatically!), multi-language support (except
flow....I think), and it has a somewhat standard output. (It exports in
RTF, or you can buy the SGML version of FrameMaker if you need it.)
In my opinion you can single source with FrameMaker easier than with any
product. I managed a large documentation project where we produced
printed docs for a UNIX-based program. It ran 28 chapters (not counting
Index) and the printed version was over 1400 pages. We developed the
version first, and within three weeks produced a printed manual from the
>From what we learned on that first pass, we modified a few approaches
estimate the conversion time from online to printed to be a week. The
docs won an Award of Merit in the 1995 STC competition in the Washington
chapter. It was not eligible to go on to the international competition
it was done on a UNIX platform and not on a Windows or Mac platform.
You author your text in FrameMaker, then save the file as LOCKED
readers need FrameViewer or FrameReader to view the files. FV costs
per seat and is available for UNIX and possibly Windows platforms. FR I
free, but lacks full text search and a few other features. It is
Mac, Windows, and I think for UNIX. For better info, check out the Adobe
page, or call Adobe's pre-sales support.
Also check out Interleaf and Worldview. I know they exist, but have
on how they work.
In response to my comment about HTML ("I'm also familiar with HTML
Netscape Navigator, but don't think they are robust enough"), Kris
I would produce nothing in a proprietary format. My recommendation is
I have done some wonderful things with tables and frames in HTML. Next,
venture into animation, sound, and video. After that, I'll be
electronic commerce transactions. All this for people using ... well, I
care what they're using.
How's that for robustness?
Please excuse the sarcasm. I'm a little on the feisty side today.
The GUIDE Family
Kit wrote: "You might want to investigate one of the products from
Inc. They have a variety of tools that are well-suited to electronic
Kit included info from their web site, which I'll summarise here:
GUIDE Author is an entry-level product to help customers get started
intelligent electronic publishing. Whether it is used for creating a
publication or a prototype for later volume production, GUIDE Author
everything necessary including full LOGiiX functionality to build an
intelligent publication. List $795
GUIDE Passport is a comprehensive, automated system for volume
of interactive electronic publications. It will import source files from
major word processors, and uses the InfoAccess template architecture to
exactly how each element within the source files translates to the
publication. Publishers have complete control over the final
can either choose from a selection of pre-defined layouts and reader
create their own custom interfaces, behavior controls and LOGiiX
Includes all GUIDE Author abilities. List price: $1,875.
GUIDE Professional Publisher (GPP) is a high end, fully programmable
electronic publishing system designed to address complex requirements.
It is an
exceptionally powerful system, used primarily for the production of
standard Interactive Electronic Technical Manuals (IETMs) and very large
publication libraries. GPP is a complete solution composed of not only
tools, but also the expert consulting and training services of
GPP provides full support for SGML (Standard Generalized Markup
source documents. In addition, it is capable of translating virtually
source format through fully programmable filters. GPP electronic
in fact, may be composed of any mix of SGML and non-SGML source
still appear as if the entire collection were compiled from a uniform
List price: $45,000.
HTML Transit is the latest InfoAccess product to employ the company s
template-based publishing architecture. It automatically produces HTML
for the Internet, supporting HTML 2 and HTML 3, as well as custom
extensions offered by leading vendors such as Netscape and Microsoft.
Chris Hamilton, Technical Writer
Greenbrier & Russel