O'Reilly & Associates, Inc.

Checklist for Selection of Document Production Tools

[Note: this document discusses isssues concerning the development of documentation for computer programs and does not explicitly treat the subject of conservation documentation. Nevertheless, some of it should be of interest to those involved in developing automated systems for handling conservation treatment documentation.
Walter Henry, CoOL maintainer]

Article 1831 of comp.text.sgml:
Newsgroups: comp.text.sgml
From: lark@ruby.ora.com (Lar Kaufman)
Subject: Checklist for Selection of Document Production Tools
Keywords: SGML document production checklist
Organization: O'Reilly & Associates, Inc.
Date: Mon, 8 Mar 1993 22:29:16 GMT
Lines: 696

This checklist provides assessment criteria and asks questions that you should answer in order to determine the usability of a proposed documentation package for creating structured documentation. The categories in this checklist necessarily have some overlap; a specific item is placed under the heading or subheading that was deemed most relevant to that item. This checklist is intended to be suitable for judging both integrated document production tools and combinations of disparate documentation tools.

This checklist was developed from information provided by editorial, design, and production staff of O'Reilly and Associates, Inc. It has been adapted for public distribution.


This document is made available for informational purposes by O'Reilly and Associates, Inc. in the hope that it will benefit software developers and users of documentation development software. It may be freely redistributed and reused. Alterations should not be attributed to O'Reilly and Associates, Inc.

This document was developed for a specific workplace, and factors were weighted according to the requirements of that workplace. While specific weighting factors have been omitted from this checklist, the criteria are biased to accomodate our existing documentation and plans for future documentation, software, and equipment, and this bias is reflected in verbiage. You should tune this checklist to reflect your own needs.

This document is not intended to imply that any particular product or service is superior or inferior to any other. Any implicit or explicit selection of one technology over another is simply a reflection of the needs of one company based on historical use and anticipated needs. Only technology known or believed to be available to the author was considered; other current and future technologies may not have received due consideration. (This document was prepared in 1992.) No representation of fitness for use is made or implied, and O'Reilly and Associates, Inc. assumes no liability for any use made of any part of this document.

Some copyrighted products are mentioned; all copyrights are the properties of their respective owners.

1 SGML Issues

Structured documentation is a critical concept in meeting our documentation needs. No other method of document preparation provides the needed document portability and adaptability of source documents to diverse presentation media. We decided that only the Standard Generalized Markup Language (SGML, ISO 8879) provides the necessary, appropriate, and fundamental standard framework for creating portable structured documentation. SGML compliance and performance is thus a critical factor in judging the suitability of tools for use. SGML, as an ISO standard, also provides a suitable standard for document tagging to permit the coordinated use of document preparation tools from different sources.

1.1 Parser Issues: How does the parser handle SGML documents?

This section concerns specific SGML implementation features that are critical or useful for our purposes in document development and publication.

1.2 Interface Issues: How does the user view and interact with the product?

This area concerns user productivity issues in SGML use.

1.3 Typesetting tool

While there are other suitable document description languages, our existing hardware commits us to mapping SGML tagged documents to PostScript and X Window output formatting.

2 General Editing

We work in a production environment where editing is done using a variety of tools by users ranging from naive to very sophisticated. The editing capabilities must reflect this diverse user base.

3 Formatting: Graphics, Composition, Layout and Style

Structured documentation rightly encourages document preparation with the focus on document organization and structure -- without focusing on output appearance. However, it is necessary to have good control of formatting of graphics, tables and figures, document layout, fonts, and many other style issues in order to have effective document production tools.

3.1 Tables, Figures, Equations and Examples

Table-making, figure-handling, and imbedding of equations, code fragments and examples into documents is a very important part of technical book production. These features should be accommodated by separate mechanisms. At least it should be possible to distinguish between these different classes of visual aid.

3.2 Graphics

Our graphics production is primarily accomplished by importing graphics produced using external tools -- often on a MacIntosh platform. Since our document production environment is X Windows-based, that work environment is critical. Output to PostScript is essential, as that provides our typesetting support. However, output to X Windows is also considered very useful; we must accomplish this output form using some tool or another; currently we convert from PostScript to X Windows in a separate step.

3.3 Composition, Layout and Style

We are very particular about style issues, and value fine control of style and layout in our production tools. We consider the distinctive appearance of our books to be a sales asset, so we must be able to tune the output to the appearance we need.

3.4 Font Control

We need the usual PostScript font support, and we expect all the tools we examine to provide this. The greatest issues are questions about how font control is accomplished.

4 Document Conversion

This is a critical area for publications. We must cope with documents in many formats from a variety of sources.

5 File Storage and Management

Document control must meet professional expectations. We have unusually complex needs for version and revision/edition control.

6 Output

Our output requirements reflect the hardware we use for production, as well as our interests in online documentation.

7 Platform/Environment Considerations

This is directed by our hardware and operating system used for production.

8 General Production and Support

We are used to having complete control over all areas of production including "hacking" our troff-based production tools. In order for us to be comfortable moving away from internally supported tools, we require some assurances that our support needs can be met in a timely manner, and that the tools we use will be developed to meet current and future needs.


Lar Kaufman lark@ora.com
Production Tools Specialist
O'Reilly and Associates, Inc. voice: 1-617-354-5800
90 Sherman Street fax: 1-617-661-1116
Cambridge, MA, 02140 U.S.A

[Search all CoOL documents]

URL: http://