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.
The following text comes from a memo I had prepared to send to
my boss and the others involved in documentation at our site.
It contains the results of the survey I conducted by asking the
TECHWR-L recipients what sort of software they use to produce
their larger manuals.
I had posted some preliminary results earlier, and received some
replies since then which affected the results. I have received several
more since then, but have not tallied them in. In truth, I don't think
they'd have affected the results, since they broke down about like
the following statistics.
----> REPORT ON TECHWR-L SURVEY ON SOFTWARE/HARDWARE
I was asked to investigate the hardware/software options available
for documentation. Perhaps the best way to do this is to check
with the people out there in the field, so I asked the subscribers to
the Technical Writing list on the Internet to tell me what they were
using for long documents (400+ pages).
About 32 people have responded. The people who have responded
have used a number of different products: Asterix, BookMaster,
FrameMaker, Interleaf, PageMaker, Quark Express,
Scribe, Tex, Ventura Publisher, Word, and WordPerfect.
One respondent uses an automatic documentation generator on the
mainframe and inputs the results into Microsoft Word on the PC
(sounded a little like DynaDoc).
The respondents overwhelmingly preferred FrameMaker and
The most common hardware platforms seem to be IBM PCs and
UNIX, followed by Macintosh. The only person who used the
mainframe to produce mainframe documentation was the person
Each of the recommended products generated a fair number of
"pro" and "con" points. By product, these points were:
* Provides a number of automatic features, like automatic
numbering of figures, sections, etc.
* Excellent bookmaking features for longer documents
* Cross-platform compatibility of files (e.g., Mac files
work on UNIX, UNIX on PC, etc.)
* Documentation compare function is available, so it's easy
to see changes
* Conditional text enables you to create several versions of
a document from a single file, lets you customize
documents for particular uses, etc.
* Easy to make tables
* Does a great job creating tables of contents, index, lists
of figures, etc.
* Easier to use than Interleaf or BookMaster
* Frameviewer allows you to distribute documents
* Ability to freeze and unfreeze pagination
* Allows you to have 2-column documentation
* Provides good drawing capabilities
* Rotation of text and graphics is possible
* Side and run-in heads
* Hypertext links
* There is a FrameMaker User Group in Pittsburgh
* Much additional power over Word
* Lacks endnote generation capability
* Harder to make quick changes than Word,
* Doesn't handle footnotes well
* Setting up an index requires work (note:
description sounds like Word's indexing process,
so I don't see it as that much more difficult)
* Has a "klunky macro facility"
* Needs a high-end machine to perform at acceptable
* "Takes some getting used to"
* Better for creating illustrations than
* Built-in Word document importing feature
"works like a champ"
* Designed to produce large technical books
* Easy to work with once the initial learning
curve is passed
* Good WYSIWYG capabilities
* Imports graphics well
* More powerful than FrameMaker
* Automated TOC, Indexing, Xref features
* List of figures must be created from a table of contents
* May be overkill in terms of power
* Product has a small market share, users are concerned about
vendor going out of business
* Does not have the "nicest user interface"
* "Occasionally has glitches that are hard to solve."
* Has a Master/Sub document feature that makes it easier than
Word to create long documents and let others work on them.
* Good indexing, TOC functionality
* Still basically just a word processor, rather than a true
% Excellent version control functions
% Flexible table creation
% Good cross-referencing features
% Pulls in artwork painlessly
% TOC and Index dynamically created
% Uses a tag-based GML that will be easy to port to SGML
% It's old technology
% Few support tools are available for it
% Not much in the way of WYSIWYG tools or capabilities
The respondents also warned me against a number of other
packages. They feel that PageMaker and Quark Express are not
suited to this kind of work - and I agree. They mentioned a
product called Scribe, and said it was powerful but not user
friendly. They also mention that long documents will bog Word
Ventura Publisher got the biggest roasting. They feel that it is a
"rickety", buggy, non-intuitive product. It required extra work to
get things done. They are also concerned that since it has been sold
to Corel Software that it won't get much attention in the way of
support or enhancement. Those who reported using it did not
recommend it to me. This, coupled with my own experiences of
the poor quality of the Mac version, leads me to conclude that we
should not consider Ventura as a solution.
From what I can see on the Internet, the vast majority of people
are using FrameMaker to produce large manuals like ours. They
have a few complaints about it, but overall seem very positive that
it is the product to use. I would therefore recommend that we give
FrameMaker a thorough shakedown to decide if it is worth using
for our documentation. FrameMaker is reported to be virtually the
same on all platforms, so we should probably try the Mac version -
unless there is an overwhelming reason to (for example) look at
the UNIX version.
--------> END OF REPORT <---------
Please note that the above information and report are my own
thoughts, observations, and opinions, and are not necessarily
those of my employer. Some of my own observations are also
included in the above, along with those provided by the people
on the techwr-l list.
I make no claims as to the accuracy, completeness, etc., of the
Questions, comments, flames, etc., may be sent to:
michael -dot- salsbury -at- cyberlink -dot- beaver -dot- pa -dot- us