This guide explains how to prepare and produce technical documentation using the IRIS InSight Professional Publisher templates and online bookbuilding tools. Users can read online manuals using the IRIS InSight document viewer, proprietary software that exploits the graphics capabilities of Silicon Graphics workstations. IRIS InSight allows readers to launch manual pages as well as applications from within an online book.
IRIS InfoSearch, a Web-based search utility, is available to view all online documentation on systems running IRIX 6.3 and above.
Online “help” is intended to be viewed through SGI Help, an application derived from IRIS InSight. SGI Help presents discrete pieces of information about an application from within the application, as opposed to the book-oriented approach of IRIS InSight. Like IRIS InSight, however, SGI Help allows readers to view portions of technical manuals and to launch other applications.
To create and edit manuals and help material to be viewed with IRIS InSight, InfoSearch, or SGI Help, use the FrameMaker document publishing application from Adobe Systems Incorporated. Use the FrameMaker tags and templates provided as part of IRIS InSight Professional Publisher Templates (IPTemplates) to structure document files so that they can be converted to Standard Generalized Markup Language (SGML) for online viewing. For manuals delivered in both print and online versions, both versions are derived from a single FrameMaker source file.
The InSight-viewable version of a technical manual is delivered as an installable software image, usually a subsystem within a software product. For this reason, you must put the component files of a viewable book through a special preparation process referred to as a bookbuild. The bookbuilding process translates FrameMaker source files to SGML using the SGIDOCBK DTD or SGIDOC DTD, and generates the additional files that are required for the installable software image.
The audience for this guide includes writers who are responsible for revising existing technical manuals and creating new ones, and production editors who prepare a writer's document source files for delivery to print vendors or to a software release group. ( It's assumed that a production editor is associated with the book and knows something about your company's document-production issues. If you don't have a production editor, you may have to handle production tasks yourself.) Experienced writers and production editors who are familiar with the SGI's book development process can refer to this guide for selected procedures and points of information. New writers and production editors should rely on this guide to learn the tools and processes with which to develop online manuals.
Readers of this guide are assumed to be experienced FrameMaker users, although detailed instructions on how to use FrameMaker's features are included.
This guide is organized to present the book development procedures in an unbroken sequence.
Chapter 1, “Getting Started”, recommends ways to become familiar with the IRIS InSight viewer and to adjust your writing style for the online reader.
Chapter 2, “Preparing Your Workstation”, explains how to organize the area of your workstation that is used during book development and how to set up the software that you will use.
Chapter 3, “Using the IPTemplates to Author Documents”, describes the templates and tags that make up the IPTemplates and how to use them when creating your documents. It also explains how to create and set up a FrameMaker bookfile.
Chapter 4, “Using FrameMaker Files and Template Features”, explains how to use the SGI document templates and their associated tags in creating a FrameMaker source file. It also explains file naming conventions and the specifics of applying FrameMaker tags to ensure the successful build of an online manual.
Chapter 5, “Working With Figures”, identifies acceptable formats for figure files and explains the purpose of directories where figure files are stored. It also explains how to process supported and unsupported figure types so that they are viewable in an online manual.
Chapter 6, “Building Online Books”, contains the procedures for converting FrameMaker source files into an online manual. It also explains how to view an online book created by the bookbuilding process.
Chapter 7, “Finding and Fixing Online Build Errors”, explains how to locate and correct problems that occur in the bookbuilding process.
Chapter 8, “ Creating Online Help” explains how to create online help for the SGI Help viewer. Help information can be either a separate document or part of an online manual.
In addition, this guide contains the following appendix:
Appendix A, “IRIS Insight Bookbuilding Architecture”, diagrams the bookbuilding architecture and process.
Refer to these documents to supplement the information in this guide:
Designing and Writing Online Documentation: Help Files to Hypertext, by William K. Horton. Published by John Wiley and Sons, Inc. For writers who want to know more about writing for the online medium.
Illustrating Computer Documentation: The Art of Presenting Information Graphically on Paper and Online, by William Horton. Published by John Wiley and Sons, Inc. Provides guidelines for illustrating and designing effective graphics in either the paper or online medium.
SGI Editorial Style Guide. Published by the SGI editorial staff to describe SGI editorial standards and preferences.
IPTemplate. Published by SGI as part of the InSight Professional Publisher distribution. These are the templates used to produce manuals. The IPchap.doc file in the /usr/share/Insight/templates/frame/IPTemplate directory contains information on how to use the various tags and features of the templates.
Using FrameMaker and FrameMaker Reference. Published by Adobe. These books document basic and advanced FrameMaker features.