This chapter explains what to do 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:
“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 write or revise a book for online presentation, take a look at an existing online book. Start by launching IRIS InSight if it's not already running; then try some of these features:
Select a topic from the Help menu on the InSight main window's menu bar.
Open a book by double-clicking its title.
Click some hypertext elements:
blue text (a link to a location in the current book)
red text (a link to a location in a different book, or to launch an application)
blue italicized word or phrase (a glossary item)
rectangle containing an arrow pointing straight right (a margin note or a footnote)
Navigate through the book. Try using the Table of Contents, the List of Examples, the List of Figures, and the List of Tables (choose Book > View) and the Index (choose Book > Index).
Click a figure to bring up a restricted view of the image.
Click a table title to bring up a restricted view of the table.
Use the text search feature.
Read through an entire chapter to get a feel for the flow of online text.
If you are using a system running the IRIX 6.3 or higher operating system, launch InfoSearch to view an online book through a browser.
Choose Toolchest > Help > Info Search to launch the InfoSearch utility.
Click Online Books to display the bookshelves installed on your system.
Click one bookshelf name and then click on any book's title.
Click one of the chapter's titles.
Click some hyertext elements:
blue text (a link to a location in the current book or to another book)
navigation arrows (located at the top and bottom of each major section)
Navigate through the book. Try using the navigation arrows.
Click on the word InfoSearch at the top of the page to return to the main InfoSearch page.
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.
When writing an online book, it might help you to be aware of the IRIS InSight features that are available to your readers. Readers can
search for specific text within one book or across an entire library
navigate through a book by clicking entries in the Table of Contents, List of Example, List of Figures, List of Tables, or Index, or by clicking cross-references
change font sizes in book windows
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
launch applications by clicking bold red text within InSight
view images, movies, and IRIS Inventor models inline
listen to audio files
view images and tables either inline or in their own separate windows
In addition, SGI online books are available for viewing on the Web via DynaWeb at http://techpubs.sgi.com/ or through InfoSearch (for systems running IRIX 6.3 and above). 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 IRIS InSight, man, or relnotes subsystems, it enables your reader to find information contained in all these SGI-supported forms of documentation.
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”.
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.
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.
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.
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.
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” |
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.
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.
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.
Linked cross-references between different books are one of the most useful features of online documentation. They do, however, involve risks. Another writer could change the organization, the content, or even the name of the referenced book. Or the book might be on a different release schedule, which means your cross-reference might be destroyed when a new version of the referenced book is released. Here are some guidelines to minimize such risks:
Avoid gratuitous cross-book references.
Notify the authors of books that you plan to cross-reference. The writers can give you an idea of how far along their books are in the revision cycle and whether the content and organization are stable.
When referring to documentation for an optional product, make it very clear that the document is optional and that the reader might not have it: “If you purchased the C++ option, see the C++ User's Guide for more information.”
The safest cross-references are to local books and books that ship with the same software product as your book.
The book development process comprises five general steps:
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”.
Write your book or update an existing book.
Use the IPTemplates and follow the directions in Chapter 3, “Using the IPTemplates to Author Documents”, and Chapter 4, “Using FrameMaker Files and Template Features”.
Add figures.
Create anchored frames and import your figures as described in Chapter 5, “Working With Figures”.
Build and debug the online version of your book.
Build the online version of the book periodically; see Chapter 6, “Building Online Books”. If you encounter errors during the build process or while viewing the completed online book, see Chapter 7, “Finding and Fixing Online Build Errors”.
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 8, “ Creating Online Help”, for instructions for making your book into an SGIHelp document.