My Doc Software Survey Results

[Michael Salsbury <michael -dot- salsbury -at- CYBERLINK -dot- BEAVER -dot- PA -dot- US>]

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
Interleaf:

   Product          % Recommending
   FrameMaker            73%
   Interleaf             15
   WordPerfect            8
   BookMaster             4
   TOTAL                100%

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

Each of the recommended products generated a fair number of
"pro" and "con" points.  By product, these points were:

FRAMEMAKER

Pro:
* 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
  electronically
* 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

Con:
* Lacks endnote generation capability
* Harder to make quick changes than Word,
  WordPerfect, etc.
* 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
  levels
* "Takes some getting used to"

INTERLEAF

Pro:
* Better for creating illustrations than
  FrameMaker
* 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

Con:
* 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."

WORDPERFECT

Pro:
* 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

Con:
* Still basically just a word processor, rather than a true
  DTP/bookmaking package

BOOKMASTER

Pro:
%       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

Con:
%       It's old technology
%       Few support tools are available for it
%       Not much in the way of WYSIWYG tools or capabilities

OTHER PRODUCTS

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

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.

CONCLUSION

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

Questions, comments, flames, etc., may be sent to:

     michael -dot- salsbury -at- cyberlink -dot- beaver -dot- pa -dot- us