This guide explains how to prepare and produce online technical documentation using the IRIS InSight™ Professional Publisher online-document-building tools. Users can read online manuals using the IRIS InSight™ document viewer, proprietary software that exploits the graphics capabilities of Silicon Graphics® workstations.
Some documentation (“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 or SGI Help, use the FrameMaker® document publishing application from Frame Technology® Corporation. Use the FrameMaker tags and templates provided as part of InSight Professional Publisher 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 book-build. The book-building process translates FrameMaker source files to SGML using the 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 Silicon Graphics 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.
This guide is organized to present the book development procedures in an unbroken sequence. These procedures are described in Chapters 1 through 4. Information on using FrameMaker features (Chapter 5) and preparing figure files (Chapter 6) is presented after the book development process; but readers are advised to refer to Chapters 5 and 6 routinely throughout the book development process.
Chapter 1, “Getting Started,” recommends ways to become familiar with the 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, “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 book-building process.
Chapter 4, “Finding and Fixing Online Book Errors,” explains how to locate and correct problems that occur in the book-building process.
Chapter 5, “Using FrameMaker Files and Template Features,” explains how to use the Silicon Graphics 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 6, “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 7, “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 appendices:
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.
IPTemplate. Published by Silicon Graphics 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 Frame Technology Corporation. These books document basic and advanced FrameMaker features.