Chapter 1. Getting Started
Prev |  | Next

## Chapter 1. Getting Started

This chapter explains how to prepare for the book development process. The chapter recommends ways to learn about the online medium and how to adjust your writing style for the online viewing audience. It also gives an overview of the book development process and tells you where to look in this book for an explanation of each step in the process.

This chapter contains these sections:

- “Before You Begin”

- “Viewer Features to Keep in Mind”

- “Guidelines for Organizing an Online Book”

- “Guidelines for Cross-Referencing in Online Books”

- “Overview of the Book Development Process”

  | Note: The writing guidelines in this chapter are very brief. For a more thorough discussion of effective online writing style, refer to the books listed as “Supplementary Reading”.

## Before You Begin

Before you write or revise a book for online presentation, take a look at an existing online book. If you are using a system running the IRIX 6.5 or higher operating system, launch InfoSearch to view an online book through a browser.

1. Choose Toolchest > Help > Info Search to launch the InfoSearch utility.

2. Click Online Books to display the bookshelves installed on your system.

3. Click one bookshelf name and then click on any book's title.

4. Click one of the chapter's titles.

5. Click some hypertext elements:

   - blue text (a link to a location in the current book or to another book)

   - navigation text (located at the top and bottom of each major section)

6. Navigate through the book.

7. Click on the word InfoSearch at the top of the page to return to the main InfoSearch page.

8. Use the text search feature.

Encourage engineering reviewers to review both the soft copy and the hard copy of your book. This is particularly important if your book is not shipped in hard copy by default.

## Viewer Features to Keep in Mind

When writing an online book, it might help you to be aware of the features that are available to your readers. Readers can

- search for specific text across an entire library

- navigate through a book by clicking entries in the Table of Contents, List of Examples, List of Figures, List of Tables, or Index, or by clicking cross-references

- open several books at the same time

- retrace their steps within a session

- get help by way of the Help menu

- print sections, chapters, or entire books

- view images

In addition, SGI online books are available for viewing on the Web at http://techpubs.sgi.com/ or through InfoSearch. InfoSearch allows users to search and browse virtually all SGI documentation: online books, man pages and release notes. Although InfoSearch does not contain every feature offered by HTML, man, or relnotes subsystems, it enables your reader to find information contained in all these SGI-supported forms of documentation.

## Guidelines for Organizing an Online Book

This section includes some tips for writing good online documentation. These tips are primarily aimed at preventing users from getting lost in the online version of a book. When writing your online book, remember that users might not see the pages in order. Further, they might not know exactly where they are in the book at any given time.

Here's an overview of basic online writing tips:

- Write in chunks. Try to make each section answer one question. Provide links to supplemental information.

- At the beginning of each chapter, provide a list of links to each of the chapter's major headings. See “Provide a Linked Chapter Summary” for details.

- Write good section headings. Make them distinct and make them descriptive enough to stand alone. See “Write Descriptive, Standalone Headings” for details.

- Be consistent in your use of terms.

- Avoid print-oriented wording. See “Avoid Print-Oriented Wording”.

### “Chunk” the Text

Usability tests indicate that readers get lost after scrolling through more than three windowfuls of text without headings. Your book will be easier to read and navigate online if you organize text in chunks: brief, to-the-point, stand-alone sections. Think of the topics in your book as index cards scattered on a desk. Readers may jump to a topic without seeing what comes before or after it. Make each section answer one question, then provide links to supplemental information.

### Provide a Linked Chapter Summary

At the beginning of each chapter, provide a bulleted list of all first-level headings in that chapter. Usability tests indicate that, when a chapter begins with a bulleted list, users expect the items in the list to be links. Use the FrameMaker cross-reference tool to create the list, so that each section heading will be a link in the online version of the book.

Of course, in some books it may not make sense to begin each chapter with a linked summary. As always, use your best judgment of what is appropriate for your book.

### Write Descriptive, Standalone Headings

A good online heading tells the reader what is contained in the section without relying on information contained in the parent heading. For instance, if a section called “Comparing Files” contains a subsection that describes how to use `diff`, name the subsection, “Using `diff` to Compare Files,” rather than simply “`diff`.”

Since your readers may enter the section from a different chapter or even a different book, using “`diff`” by itself as a subsection title doesn't provide enough context information; it requires the reader to skim the previous section and to know what the `diff` utility is used for.

To make it easy for a reader to stay “located” in your book, stick to one topic per section. If the subject changes, write a new heading. Don't worry about having too many headings; a large number of headings will make your document more usable and won't overload it.

### Use Terms Consistently

Online readers leap quickly from section to section. While looking for information on a particular topic, a reader might consecutively read eight different paragraphs from various chapters in your book, and others from another book as well. So, for example, if you call something a “short name” in one chapter and a “short title” in another, and another writer calls it a “shorty” in a different book, readers may get confused. This kind of inconsistency is inadvisable, in a hard copy book, but it's deadly online. If you change a term partway through the writing process, use FrameMaker's Edit > Find/Change tool to make sure you change all the occurrences of the old term.

### Avoid Print-Oriented Wording

Online readers approach information from many different directions. Don't assume that a reader knows or has read information that isn't currently on the screen. Avoid wording that refers to location within a book, unless you also create a link to that information. Table 1-1 gives examples of how to avoid print-oriented wording.

Table 1-1. Suggestions for Avoiding Print-Oriented Wording

Use... | Instead of...
--- | ---
“in the section named...” | “as shown above (or below)”
“in Chapter 3, you learned that...” | “by now you have learned that”
“in the previous section, <section title>,” | “in the previous section”

## Guidelines for Cross-Referencing in Online Books

In the online version of your book, local cross-references appear in blue and are linked to the referenced material. This gives your readers another way to navigate the book. Well-designed cross-references get information to the people who need it, and keep it out of the way of those who don't. Poorly designed cross-references can lose readers in annoying and confusing wild goose chases. This section offers some guidelines for good cross-referencing.

### Write Informative Cross-References

Include enough information in a cross-reference so a reader can decide whether to follow it. For example, “See the Origin200 Owner's Guide” doesn't tell the reader what information you are referencing. A better reference might be, “See the section called `Setting Up Your System' in the Origin200 Owner's Guide for more information about plugging in the power cord.” This reference tells the readers exactly what information they can expect to find at the other end of the link.

### Cross-Reference Repeated Information

Avoid including the same information in multiple places in your book. Instead, put it in the most important place, then create cross-references to it as necessary. This way, readers who need the information can just click the cross-reference, while readers who don't need it won't need to scroll through it. And when you need to update the information on that topic, you won't have to remember to update it in more than one place.

## Overview of the Book Development Process

The book development process comprises five general steps:

1. Prepare your workstation.

   The first step in developing a book is to set up the software tools on your workstation. See Chapter 2, “Preparing Your Workstation”.

2. Write your book or update an existing book.

   Use the SGI Book Building Templates and follow the directions in Appendix A, “Using the SGI Book Building Templates to Author Documents”, and Chapter 3, “Using FrameMaker Files and Template Features”.

3. Add figures.

   Create anchored frames and import your figures as described in Chapter 4, “Working With Figures”.

4. Build and debug the online version of your book.

   Build the online version of the book periodically; see Chapter 5, “Building Online Books”. If you encounter errors during the build process or while viewing the completed online book, see Chapter 6, “Finding and Fixing Online Build Errors”.

5. Add help topics to your FrameMaker files and create helpmaps if some or all of your book's contents act as “help” for an application or utility.

   See Chapter 7, “Creating Online Help ”, for instructions for making your book accessible from the SGIHelp system.

## SGI Book Building Architecture

Figure 1-1 shows the general process flow for building the textual content of an online book.

Following the figure is a more detailed text description of the process.

Figure 1-1. Architecture for Book Building

Authors compose a book using FrameMaker, then “compile” the book into an online book:

- The FrameMaker files (`.doc, .fm`) are converted to Maker Interchange Format (`.mif`) using FrameMaker's `fmbatch` utility. A special file, `conditional.doc`, is used during this process to force the proper FrameMaker conditionals to be applied.

- The next phase is to translate the MIF files (`.mif`) into SGML files (`.sgm`) using a MIF to SGML translator such as `mif2sgml`, a translator from SGI. After each file is translated, the `.sgm` file is scanned to see whether it contains any CGM figure references. CGM figures are generated from FrameMaker line art. If the `.sgm` file contains CGM figure references then it is run through Inso's `miftocgm` utility and every anchored frame is converted to a CGM image. The file is scanned again to convert the CGM images to GIF images.

- Once all the SGML files have been generated for the book, they're concatenated and the `indexgen` utility is run over them to create a back-of-the-book index. This index is then concatenated to the rest of the SGML files, and a document bounding tag pair is wrapped around the result to create the master SGML file.

- The SGML instance is transformed into the industry-standard DocBook XML DTD (markup/format). This involves the use of the open source tool xsltproc, the XSL (XML Stylesheet Language) transformation engine, along with the SGI filter (sgml2xml). Using the XSL stylesheets for DocBook XML, along with an SGI customization layer, the xsltproc engine is again utilized to produce various output formats to be used for distribution. The resultant output is a set of HTML files and related metadata files.

## Advantages of the Book Development Process

Starting with the 5.0 version, the SGI Book Building Tools provide support for DocBook XML in building HTML online books. As an online documentation delivery solution, you will benefit from extra performance, format standardization, and process efficiencies. The advantages built into this process include:

- DocBook source files allow building on top of standard XSLT stylesheets

- Many available DocBook and XML tools and customizations (new tools continue to be developed)

- HTML files created with SGI process are faster to load and use when following cross references

- Create documentation CDs with both HTML and PDF files that can be used on any operating system

- DocBook makes it possible to create document deliverables for portable devices

- Environment can be leveraged for Linux OS document deliverables and build environment

- Allows for simple ISV integration and 3rd party document assimilation.

Prev | Table of Contents | Next
About This Guide |  | Chapter 2. Preparing Your Workstation