This guide explains how to prepare and produce technical documentation using the SGI Book Building Templates and SGI Book Building Tools. Users can read online manuals using any web browser or InfoSearch.
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 SGIHelp, the IRIX Interactive Desktop™ help system. It presents discrete pieces of information about an application. SGIHelp viewer provides an easy-to-use interface which allows the user to browse through help information for most applications shipped by SGI. It can be launched from within an application itself, utilizing the application's Help menu or a Help pushbutton.
To create and edit manuals and help material to be viewed with a web browser, InfoSearch, or SGIHelp, use the FrameMaker document publishing application from Adobe Systems Incorporated. Use the FrameMaker tags and templates provided as part of the SGI Book Building Templates to structure document files so that they can be converted to Standard Generalized Markup Language (SGML) for processing. For manuals delivered in both print and online versions, both output are derived from the same FrameMaker source file or book.
The HTML 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 required for the installable software image.
The audience for this guide includes writers 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 the SGI Book Building Templates 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 book development process 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 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 4, “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 5, “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 6, “Finding and Fixing Online Build Errors”, explains how to locate and correct problems that occur in the bookbuilding process.
Chapter 7, “Creating Online Help ” explains how to create online help for the SGIHelp viewer. Help information can be either a separate document or part of an online manual.
In addition, this guide contains the following additional resources:
Appendix A, “Using the SGI Book Building Templates to Author Documents”, describes the templates and tags that make up the SGI Book Building Templates and how to use them when creating your documents. It also explains how to create and set up a FrameMaker book file.
Appendix B, “Building DocBook XML Books”, introduces DocBook XML and how it can be used to create online books as an alternative to FrameMaker based books.
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.
Using FrameMaker and FrameMaker Reference. Published by Adobe. These books document basic and advanced FrameMaker features.
The SGI Book Building Templates are provided by SGI as part of the
SGI Book Building Environment 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.
DocBook: The Definitive Guide, by Norman Walsh, and Leonard Muellner. Published by O'Reilly. This book contains an introduction to SGML, XML, and the DocBook DTD, plus the complete reference information for DocBook.