Technical Style Guide

TECHNICAL PUBLICATIONS
STYLE GUIDE
Center for Bioinformatics
Revised July 10, 2006

Table of Contents
Chapter 1 Introduction.............................................................................................................................. 1
Chapter 2 Documentation Schedule/Process .......................................................................................... 3
Documentation Plans ....................................................................................................................... 3
Technical Publications Life Cycle .................................................................................................... 4
Writing Content ................................................................................................................................ 4
Getting Reviews ............................................................................................................................... 5
Finalizing .......................................................................................................................................... 6
NCICB Intranet—Adding and Revising Documents......................................................................... 8
Chapter 3 Document Content .................................................................................................................. 9
Chapter 4 Using Microsoft Word™ ........................................................................................................ 13
Table of Contents........................................................................................................................... 13
Glossary ......................................................................................................................................... 15
Indexes........................................................................................................................................... 16
List of Tables or Figures................................................................................................................. 20
Styles.............................................................................................................................................. 21
Numbering Headings and Paragraphs........................................................................................... 24
Auto-numbering Chapters and Appendixes ................................................................................... 24
Auto-numbering Lists ..................................................................................................................... 26
Page Numbers and Page Breaks .................................................................................................. 28
Headers and Footers ..................................................................................................................... 29
Cross-References .......................................................................................................................... 31
Images ........................................................................................................................................... 33
Tables............................................................................................................................................. 35
Callouts .......................................................................................................................................... 36
Captions ......................................................................................................................................... 39
Creating a PDF from Word ............................................................................................................ 41
MS Word™ Tips, Tricks, and Troubleshooting .............................................................................. 42
Chapter 5 Using Adobe FrameMaker™................................................................................................. 47
FrameMaker™ Tips, Tricks and Troubleshooting.......................................................................... 47
Chapter 6 Creating Online Help ............................................................................................................. 61
Frequently Asked Questions (FAQs) about Online Help ............................................................... 61
Elements of Online Help ................................................................................................................ 62
Online Layout and Format ............................................................................................................. 63
Software for Creating Online Help ................................................................................................. 64
Generating the Online Help Project ............................................................................................... 64
Finalizing Online Help .................................................................................................................... 68
Chapter 7 Style and Mechanics ............................................................................................................. 71
Bibliographies................................................................................................................................. 71
Logos.............................................................................................................................................. 72
Copyright........................................................................................................................................ 72
Punctuation .................................................................................................................................... 72
Sentence Structure ........................................................................................................................ 76
Precision in Writing ........................................................................................................................ 79
Text Conventions ........................................................................................................................... 80
Word Usage ................................................................................................................................... 81
Chapter 8 Slide Preparation ................................................................................................................... 87
Chapter 9 References for Technical Writers .......................................................................................... 89
Appendix A Making Edits in a PDF ............................................................................................................. 91
Index............................................................................................................................................................ 95
This is a U.S. Government Work. i

Introduction Chapter 1
Chapter 1 Introduction
Overview The Technical Publications Style Guide is designed to help you quickly find
information you need to write documentation for software technical guides,
user’s manuals, or training materials to be used internally or disseminated
by NCICB. It is intended to be a reference guide to achieve a consistent style
among different writers and between different products.
This Style Guide uses the methods and styles that it suggests throughout.
The format of this style guide is Information Mapping, a format discussed on
page 10.
1
Technical Publications Style Guide
This page is intentionally blank.
2
Documentation Schedule/Process Chapter 2
Chapter 2 Documentation Schedule/Process
Overview To produce on-time and accurate documents for software releases, a

documentation plan should be prepared in advance of the beginning of a
release. The documentation plan identifies deliverables and deadlines.
Deadlines that are not met within a release can easily be identified as areas
for improvement in the next release.
Other organizations involved in the development life cycle such as

development and QA should be encouraged to review documentation plans
to understand how changes in these areas affect documentation and vice
versa.
This chapter discusses what a documentation plan consists of and how it is

used.
Documentation Plans
Preparing a Before the beginning of a release cycle, a documentation plan should be
Documenta- established. The plan should include, at the minimum, the following:
tion plan • a list of known content changes/bug fixes
• a list of documents that will be delivered for the release
• the person who will author each document
• names of reviewers
• a list of known risks that may affect the delivery of the documentation
• a schedule of deadlines that will be met during the release
The schedule should be based on the expected release date and allow time
for the following phases of the writing and publishing process for each
manual:
• gathering requirements
• generating outlines
• writing content
• preparing cover art
• expected date of function freeze
• expected date of UI freeze
• technical review
• editorial review
• final editing and polishing
• publishing and reviewing proofs
• publishing final documents
• preparing electronic documents
• archiving final documents
• preparing erratas
The phases of the schedule are discussed in the next section.
3
Technical Publications Life Cycle
Writing Content
Gathering Before the beginning of the release cycle, acquire a list of new features and
Requirements bugs from Product Management or Development to establish accurate
content. If such a list is not available at the beginning of a release, this
should be listed as a risk in the Documentation Plan. This list can be also be
used as a checklist to make sure that major areas are covered.
Also acquire any documentation such as white papers, functional

requirements documents (FRD), test track information or developer
documentation that can be used in writing new content or revising existing
content.
Finally, find out information about the frequency of builds, which servers are
accessible to writers on the project, and whether data is available or must be
generated to understand and write about a topic.
Preparing • NCICB—A cover template for NCICB documentation has been designed
Cover Art for NCICB. The template is available in MS Word or Adobe FrameMaker
format. NCICB cover art must include three logos, NCI, NIH, and DHHS.
For more information about these logos and where they can be obtained,
see Logos on page 72.
• caBIG™—Cover templates for caBIG documentation has been designed

by the Documentation and Training workspace. The templates are
available on the Training Portal of the caBIG website:
https://cabig.nci.nih.gov/working_groups/Training_SLWG/Documents/ind
ex_html.
Generating Before writing content, establish a brief outline of the text and convert it to a
Outlines table of contents draft. At that point, you can even create the book file and
/Writing add content to the draft as you write the material.
Content
Content should be written throughout the course of the development life
cycle. Open dialogs should be established between writers, developers, QA
and other subject matter experts.
If an existing document exists and is being revised, decide how you want to
mark new content, especially if you can save a reviewer’s time by only asking
for a review of what has changed in the release.
If there are build notices during a build cycle that the technical writers have
access to, they can easily be compiled into release notes.
Goals for completing content should be established based on the order in

4
which the functionality is coded by development and made available in

builds. Installation material should be documented last as this is commonly
an area that is tested last and where late changes occur in a build cycle.
Getting Reviews
Technical Once a content deadline is reached, a document should be distributed to one
Reviews or more subject matter experts for a technical review. Reviewers of this type
might be developers, QA, DBAs, or application scientists.
A technical review should be coordinated with function and UI freezes (if

these occur). The purpose of a technical review is to evaluate content
completeness and accuracy. If a document is missing information, it is not
ready for a technical review. If there are major changes to an application
after a technical review, the document should be revised and the edit
repeated.
If there is time in the schedule, a technical review should be done first and be
followed by an editorial review. Otherwise, the two can be done
simultaneously.
Give technical reviewers the following:

1. The document’s location or a hard copy
2. Specific instructions to evaluate the accuracy and completeness of
the document and whether the document meets its stated purpose
(for example, an installation manual should tell a user how to install
an application accurately but not necessarily how to use the installed
application).
3. Encouragement to avoid correcting grammar, spelling, layout etc. An
editorial reviewer covers these areas.
4. A reasonable deadline (for example, 1 week per 100 pages)
5. Specific instructions about how you want the document commented
(for example, mark a hard copy with red pen or make comments in an
electronic copy).
6. A sign-off sheet to indicate who reviewed a document and the date of
review.
NOTE: Documents generated in Adobe FrameMaker™ must be reviewed in pdf

format. Technical writers with full versions of Adobe Acrobat™ v. 7.0
Professional can save documents as “Reader-enabled” so that reviewers
who do not have full versions of Adobe Acrobat™ can perform their
reviews in Adobe Reader™ which is a free application.
5
Editorial If there is time for a technical review prior to an editorial review, changes
Reviews from the technical review should be incorporated before distributing a
document to one or more writers for an editorial review. The purpose of an
editorial review is to clean up grammar, spelling, and organization issues and
to finalize the document before publishing.
If a document has areas that need improvement based on the technical

review, it is not ready for an editorial review. This is also not the time for
major content changes.
In addition to incorporating technical comments and last minute UI changes,

do the following before distributing a document for an editorial review:
Step Action
1 Check spelling
2 Proof for gross errors
3 Label captions
4 Set up headers, footers and page numbers
5 Cleanup and update index and TOCs
6 Name the document by the convention,
Product/Version#_NameOfManual_Date _Initials (for example,
caCORE_SDK_Guide_012405_jbh), and place in the appropriate
network group directory:
Example
L:\Technical Writing\caCore ToolKit\caCORE SDK Guide Drafts after
010105
7 Backup the document locally
8 E-mail the editor a README file that includes:
• the document’s name and location
• a to-do list of formatting issues that remain (for example, “can’t get
the page numbers to number correctly – please correct them”)
• a review deadline
Finalizing
Final Editing The last step in the editing process is incorporating comments from the
& Polishing editorial review and checking the final format.
The goal of this step is to ensure that the final document has no errors. In
other words, once a manual is converted to pdf format, formatting and
content changes should not be required if the manual has been reviewed
carefully.
This step is a shared task between the author and the final editor, who
should complete the following edits:
Author’s Editor’s Task

Responsibility Responsibility
5 N/A Technical and editorial reviews are
complete and changes are incorporated
6
Author’s Editor’s Task

Responsibility Responsibility
5 N/A Technical support numbers are updated
5 N/A Title and copyright pages (where
appropriate) are updated
5 5 Grammar/spelling is checked
5 5 Headers, footers, and page numbers
are correct
5 5 Cross-references are checked for
errors
5 5 Indices are updated
5 5 TOCs are updated and TOC links are
removed from actual TOCs
5 5 Hard copy page turn and general proof
is done. Check for incorrect page
breaks and graphics clarity
5 5 Document is saved to appropriate
network directory and backed up.
N/A 5 Cover art is prepared
Version If a document does not need to be shared until it is ready for review, writers
Control are encouraged to keep working documents on their local drives. They
should back up their documents regularly on the network server.
When a document is ready for an edit or a proof, the document should be

named using the convention, Product/Version#_NameOfManual
_Initials_Date (for example, caCORE_SDK1.0_Guide_012405_jbh), and
placed in the appropriate network directory.
Preparing Once manual documents have been finalized and approved, a .pdf file is
Electronic made of each document that is included in a release. The .pdf file of each
Documents document must be forwarded to the webmaster, who posts it on the website.
Preparing If erratas are ever necessary, the entry to an errata should be literal so that
Erratas the user can understand the incorrect text and the correct text that is
replacing it. A page number and section heading, where possible, should
also be provided for each entry.
Example:
Technical Guide
Under the section “Assigning Customer-Specific Directories” on page 59, replace the
commands at the top of page 60 that read:
% cd /g3/java/cgi-bin
% mkdir ncicb
% ln –s *.cgi ncicb/
7
with the following commands:
% cd /g3/java/cgi-bin
% mkdir ncicb
% cd ncicb
% ln -s ../*.cgi ./
Immediately after the newly inserted commands, insert the following:
Note: To make the symbolic links to the cgi files in the ../java/cgi-bin directory from a
user-specific directory, the ln –s command must be executed from the user-specific
directory (the L:\ncicb directory in the above example).
Archiving Once documents are finalized, archive all documents for a release by
placing them in the appropriate archive directory on your network.
NCICB Intranet—Adding and Revising Documents

NCICB The NCICB Intranet is set up so that many developers and managers at
Intranet NCICB can edit the site when necessary. If you have been given management
Management access to edit this section of the Intranet, so you can upload revised versions
Access of the document or add new content yourself without waiting for Application
Support personnel to post it.
Your current Intranet username/password will allow you to edit using a web
browser and some simple HTML copy/paste skills. Application Support has
posted a document to the Intranet to explain how to perform simple document
and HTML management tasks.
http://ncicbintra.nci.nih.gov/intra/intranetlfs/NCICBIntranetContentManagerUse
rGuide.doc
8
Document Content Chapter 3
Chapter 3 Document Content
Overview Using common organizations between books and in chapters within a book
gives all manuals, even if they are for different product lines, the same look
and feel.
Book The manuals should have the following basic organization*:

Organization • Title page
• Copyright page (where appropriate)
• Table of Contents at a Glance (if the document is large) & Table of
Contents (see Table of Contents on page 13)
• Chapters
• Appendixes
• Glossary
• Index (See Indexes on page 15)
*This organization may be modified based on book content.
Chapter Each chapter in a manual should have the following sections:

Organization These are generic outlines for a user’s manual.
• Introduction
• Topics In This Chapter Include
• Overview of processes
• Before you begin
• Workflow
• Where to go from here
Template The following styles are contained in the MS Word base template. These
Styles styles should not be changed; instead a new style should be created based
on an existing style.
Appendix Caption = (auto numbers based on Appendix Heading 1)

Appendix Heading 1 = first level heading - appendix title (auto numbers)
Body Text =
Body Text Indent =
Body Text Indent 2
Block =
Bulleted
Bullet Indent =
Bullet Indent 2
Chapter Caption = (auto numbers based on Heading 1)
Code =
Caption
Heading 1 = first level heading - chapter title (auto numbers)
Heading 2 = second level heading
9
Heading 3 = third level heading

Heading 4 = fourth level heading
Note =
Numbered List = (auto numbers)
Table Text headings
Table Header
Storing Files for storing documentation templates should be located in directories to

Templates which all writers have access.
Information Information mapping is a method of writing and document layout that makes
Mapping complex information easy to use. It involves using visible structure to
enhance initial learning and information retrieval. Technical writers of small
manuals can use this method of organization and writing.
Note: This Technical Style Guide uses the information mapping layout.
There are four basic principles of information mapping:

1. Chunking
2. Relevance
3. Labeling
4. Consistency
Principle Description
Chunking principle Group information into small,

manageable units consisting of one to
nine pieces of information. This is
because people generally can remember
no more than seven plus or minus two
pieces of information at one time.
This principle is used throughout this

style guide.
Relevance principle • Place like things together
• Exclude unrelated items from each

chunk.
Labeling principle Provide the reader with a label for each

chunk of information
10
Document Content Chapter 3
Consistency principle Use consistent:
• Terms within each chunk of

information
• Terms in the chunk and the label
• Organization
• Formats
Integrated graphics Use tables, illustrations and diagrams as

an integral part of the writing
Accessible detail Write at the level of detail that will make

the doc usable for all readers
Hierarchy of chunking and labeling • Group small chunks around a single

relevant topic
• Provide the group with a label
11
12
Using Microsoft Word™ Chapter 4
Chapter 4 Using Microsoft Word™
Overview Although the software of choice for generating most guides and manuals at
NCICB is Adobe™ FrameMaker™, the technical writing group sometimes
uses Microsoft Word for writing small guides and manuals. The following
sections provide instructions for using Word to create certain document
elements such as TOCs, glossaries, indexes etc. and applying preferred
styles to these elements.
For more robust documentation, the NCICB technical writing team uses
Adobe FrameMaker™. For more information, see Chapter 5 Using Adobe
FrameMaker™.
NOTE:
caBIG™ documentation should be generated using templates designed by
the Documentation and Training Workspace. You can download these
templates from the Training Portal on the caBIG website:
https://cabig.nci.nih.gov/working_groups/Training_SLWG/Documents/inde
x_html.
Table of Contents
Generating a Two kinds of TOCs can be present in manuals: a simple Table of Contents
New TOC at a Glance that includes only Level 1 Headings (recommended only ifor
large manuals) and a detailed Table of Contents that includes Level 1 and 2
(Level 3 optional) Headings. To generate a table of contents that includes
both chapter and appendix headings, use the following steps:
Step Action
1 Place the insertion point in the intended location for the table of contents.
Click Insert > Index and Tables and select the Table of Contents tab.
2 Click the Options button.
In the TOC level boxes, in the text box to the right of Chapter Heading,
type 1. This configures Word to consider Chapter Heading to be a Level
1 entry in the table of contents. Do the same for Appendix Heading,
Index Heading, and any other headings you want to appear in the TOC.
Hint: If you create a separate Heading 1, TOC style, any text that is
formatted with a Heading 1,TOC can be designated not to be placed in
the TOC.
Click OK. The Print Preview displays.
13
Step Action
2 For a Table of Contents at a Glance, type 1 in the Show levels box.
This only generates a list of Level 1 Headings.
For a Table of Contents, type 2 (or 3) in the Show levels box. This
generates a list of Level 1 though 2 (or 3) Headings.
3 Leave Formats set to From template.
Make sure that the Right align page numbers check box is selected
and the Tab leader is set to ( …) .
4 Click OK in the Index and Tables dialog box to generate the TOC. Word
has default TOC styles (TOC 1 thru TOC 9) that are applied
automatically when a TOC is generated.
An example of a Table of Contents with Levels 1 thru 3 Headings that

includes Chapter, Appendix and Index is shown below.
5 If you have not removed Heading 1 TOC from the level 1 headings
during TOC setup, make sure you remove it from the TOC. Press CTRL
+ SHIFT + click to highlight the line and then delete it.
Updating an TOCs can be updated by page numbers only or by updating the entire table.
Existing TOC To update a TOC, use the following steps:
Step Action
1 Update a TOC only by clicking anywhere in the TOC (press CTRL + SHIFT
first) and then pressing F9 or selecting Update Fields from the shortcut
menu opened with a right click.
To update the TOC and all cross-references and index markings in the
entire document, select Edit > Select All or press CTRL + A, Then press
F9.
NOTE:
Be sure and review a document after finishing a
complete update. An update seems to sometimes
introduce anomalies in layout and formatting can you
can fix manually.
14
2 In the Update Table of Contents (shown in following figure) select the

radio button corresponding to Update page numbers only or Update
entire table.
Click OK.
.
3 If you have not removed the Heading 1, TOC from the level 1 headings
during TOC setup, make sure you remove it from the TOC. Press CTRL
+ SHIFT + click to highlight the line in the TOC and then delete it.
TOC Styles The styles TOC1 through TOC9 are automatically created when a TOC is
generated the first time in a document. The style Hyperlink is also
automatically created. In manuals, these styles use the default Word
settings.
Tips • To format text manually in the TOC, press CTRL + SHIFT + CLICK where the
correction is needed and type the correction. To move the cursor, select
the line and then click the left or right arrow key.
Note: Edits made in the TOC itself will be overridden when the TOC is
updated. For permanent edits, make them in the source text.
• To convert the TOC to text from a hyper-linked, generated list, press CTRL
+ SHIFT + F9.
• Clicking File > Print Preview forces an update.
Glossary
Glossary • The Glossary in a guide is generally located just before the Index. A
Content Glossary can be packaged as an appendix.
When determining what words should be included in the glossary:
• Define all terms unfamiliar to a general reader.
• Define all terms that have a special meaning in the document
• Define only terms that that need explanation.
15
Indexes
Selecting As you analyze a topic for inclusion in an index, decide whether the topic
Topics to contains information a user may expect to find in the index. To determine
Index whether a topic justifies an index entry, analyze the topic for the following
attributes. Create an index entry when a topic:
• Describes how to perform a task

• Contains a definition of a term
• Is an acronym or abbreviation
• States a restriction, such as a Caution or Warning
• Explains a concept or an idea
In selecting topics to index, note the following:
• Avoid using headings as index entries

• Include only terms a reader is likely to look up
• Arrange words for emphasis
• Don’t use a two-level entry for a single topic, such as:
Range
in filtering algorithms
Use instead:
Range, filtering algorithms
Double- or triple-posted entries:

• Include index markings for all variations of a short phrase. For
example, a section describing how to open Text Pane folders could
be indexed in three ways:
1. Text Pane, opening folders

2. Folders, opening in Text Pane
3. Opening, Text Pane folders
Using See References:

• Include references to other index markings where appropriate such
as:
Figure, See Image
• Avoid using unnecessary “See” references.
16
Marking an Index markers can be inserted by page or by page range. To create an index
Index Entry marker, use the following steps:
Step Action
1 To enter an index marker, press SHIFT + ALT + X or select Insert >
References > Index and Tables (in Word 2003), Index tab and click
Mark Entry.
In the Mark Index Entry dialog box, enter keywords in the Main entry
and Subentry fields. Press ENTER or click Mark.
Note: Once you enter a new index marking, field codes for all markings
display in the document.
2 Click the Cross-reference, Current page, or Page range** radio button
and click Mark.
**To insert an index page range, first create a bookmark with the page
range.
1. Select all text within the page range in the document.
2. Click Insert > Bookmark, name the bookmark and click Add.
3. In the Mark Index dialog box, select the Page Range radio button.
In the drop down menu, select the bookmark name for the page
range.
4. Click OK.
3 To view index markings as well as other formatting markings in the
document, click the paragraph button on the Standard toolbar.
Generating an Generating an index should be one of the last steps in finishing a document.
index To generate an index, use the following steps:
Step Action
1 Place the insertion point in the intended location for the index.
Click Insert > Index and Tables and select the Index tab.
2 Select Classic from the Formats box.
Leave the Indented radio button selected in the Type field and the
Column box set to 2.
Make sure that the Right align page numbers check box is selected
and the Tab leader box has … selected.
3 Click OK in the Index and Tables dialog box to generate the index.
Word has default Index styles (Index 1 thru Index 9 and Index Heading)
that are applied automatically when an index generated.
17
NOTE:
Before generating an index, make sure to close all field codes in the
document (by clicking the Paragraph symbol on the toolbar). If the index is
generated with field codes displayed and then you close them to finalize the
document, the page number references will be incorrect.
Editing an Once an index is generated, it should be carefully reviewed for duplicate

Index entries and mistakes. In editing the index, check for the following:
Check the spelling

Check for differences in wording, for example (incorrect)
Creating
new CDE
Create
class diagram
Check for misused singular and plural forms, for example (incorrect)
CDE
creating new
CDEs
creating objects for
Check for differences in capitalization, for example (incorrect)
Class diagram
in caCORE
Class Diagram
description
In each of these examples, the differences in index primary keywords will

result in separate index entries; there will be six when there should be three.
Tip: To expedite editing an index in Word, use the following steps:
Step Action
1 Click Tool > Options > Wrap to Window and then Window > New
Window to create a copy of the open document.
2 Click View > Normal in each window, reduce the size of each and tile
horizontally with the left window only wide enough to accommodate one
row of index. Click the paragraph button on the Standard toolbar to show
the index markings.
3 Return to the index and press F9 to update it with the modified page
numbers (showing all markings modifies text placement) so they will
correlate with the index markings when you try to find them.
4 Review the index for problems in the left window. In right window, find
the pages and field codes for problems and fix them right in the code.
18
Step Action
5 Click the paragraph button on the Standard toolbar again to hide the
index markings. Select and update the index again to correct the page
numbers without the space taken up by the field codes.
Updating an Indexes, just like TOCs, can be updated by page numbers only or by
Existing Index updating the entire table. To update an index, use the following steps:
Step Action
1 Update an index by clicking anywhere in the index and then pressing F9.
To update the index and all cross-references and TOC markings in the
entire document, select Edit > Select All or press CTRL + A, Then press
F9.
NOTE:
Be sure and review a document after finishing a
complete update. An update seems to sometimes
introduce anomalies in layout and formatting can you
can fix manually.
2 Review the index to make sure that are no formatting errors.
NOTE:
Before updating an index, make sure to close all field codes in the document
(by clicking the Paragraph symbol on the toolbar). If the index is updated with
field codes displayed and then you close them to finalize the document, the
page number references will be incorrect.
Index Styles The styles, Index 1 through Index 9, are automatically created when an index
is generated the first time in a document. The style Index Heading and
Hyperlink are also created automatically. In manuals, these styles use the
default Word style settings.
You can correct inappropriate individual index entry styles by returning to the
field code for the entry and removing the italic or bold markings, for instance,
or by correcting the style in the index after you have updated it for the final
time. If you correct it using the former method, you will not have to continually
correct the style each time you update the index.
Indexing Tips • Keywords that are used multiple times must be entered exactly the same
to be considered the same entry by Word. When one or more extra
spaces are present or when the case of an entry is not consistent,
different index entries are created. For example, the entries index and
Index would be included as different entries.
19
• To convert the index to text from a hyper linked, generated list, press
CTRL + SHIFT + F9.
• Wrong page numbering, mis-placed alphabetization, and page numbers
with no keyword is most likely due to a corrupt document (most formatting
is stored in last paragraph mark.) To fix this, try the following:
1. Press CTRL + END (cursor goes to end of document) then CTRL +
SHIFT + HOME (selects entire document excluding last paragraph
symbol).
2. Press CTRL + C to copy.
3. Paste in new Word document.
4. Regenerate the index. Formatting problems should be corrected.
List of Tables or Figures

Generating When figures and tables are captioned in a document, a list of figures or
Lists of tables can be generated and placed in the beginning of the document. (This
Tables and is optional for documents at NCICB.) To generate a list of tables of figures,
Figures use the following steps:
Step Action
1 Place the insertion point in the intended location for the List of
Tables/Figures.
Click Insert > Index and Tables and select the List of Figures tab.
2 Leave the setting as the defaults: Show page numbers and the Right
align page numbers check boxes selected, Tab leader set to …, and
Formats set to From template.
3 Select the type of caption (table, figure, or equation) from the Caption
label list.
4 Click OK. The list is generated as in the example of a list of tables
shown in the example below.
List Styles The styles, Table of Figures/Tables/Equations, are automatically created

when a list is generated the first time in a document. In manuals, these styles
use the default Word style settings.
20
Tips • Keywords that are used multiple times must be entered exactly the same
to be considered the same entry by Word. When one or more extra
spaces are present or when the case of an entry is not consistent,
different list entries are created. For example, the entries figure and
Figure are included as different entries.
• To convert the index to text from a hyper linked, generated list, press
CTRL + SHIFT + F9.
Styles
Creating a To create a new style, use the following steps:
Style
Step Action
1 Select Format > Styles and Formatting. At the top of the right sidebar
that opens, click the New Style button.
In the Style dialog box, select the style you want to base the new style
on from the Styles list (by default, new styles are based on Normal) and
click New.
2 In the Style dialog box, select the style you want to base the new style
on from the Styles list (by default, new styles are based on Normal) and
click New.
3 In the New Style dialog box, name the style, select a style format
(character or paragraph), and select a style for the following paragraph
(for example, select Body to always follow Heading 2).
Note: You can also change the base style in the New Style dialog box.
4 Select the Add to template check box.

5 Click the Format drop-down and change the Format, Font, Tabs, etc.
6 Click OK and then click Apply. The new style is added to the list of
styles.
21
Heading Wise choice of heading styles can keep a layout simple and uncluttered.
Styles • Differentiate major and minor topics clearly.
o Indicate the scope and importance of a topic by varying type sizes
and styles: big and bold for chapter headings, small and plain for less
important headings.
o Avoid using italics in headings unless you are certain it does not
interfere with legibility.
• Always use upper- and lowercase letters; uppercase letters alone are
difficult to read. If you want the emphasis conveyed by uppercase letters,
use large and small caps. Use indentation to indicate less important
topics.
• Avoid using “mil spec” numbering. Numbers prefacing headings not only
are distracting, but they make it difficult to scan titles.
See also Word Choice for Titles on page 81.
Modifying a To modify an existing style, use the following steps:

Style
Step Action
1 Select Format > Style. In the Style dialog box, select the style you want
to modify from the Styles list and click Modify.
Word 2003: The selection Format > Styles and Formatting opens a
“catalog” of styles at the right of the viewing screen. Right click on the
style you wish to modify, and select Modify Style from the shortcut
menu.
2 In the Modify Style dialog box, change the style format (character or
paragraph) and change the style for the following paragraph (for
example, select Body Text to always follow Heading 2).
Note: You can also change the base style in the New Style dialog box.
To make major changes to style formats, click the Format button in the
dialog box and make your selection from the dropdown list. Make the
appropriate changes in the dialog box that opens and click OK.
In the Modify Style dialog box, check the Add to Template checkbox to
set the modified style to the template.
Warning: Do NOT check the Automatically update checkbox. That will
create havoc in your document and may even lead to baldness (from
tearing your hair out!!).
3 Select the Add to template check box.
4 Click the Format drop-down and change the Format, Font, Tabs, etc.
5 Click OK and then click Apply. The changes are added to the style.
22
Copying Styles can be copied directly between two documents or from a document to
Styles a .dot file and then to a second document.
Between
Documents When you want to add styles to a document directly from a template or
another document, locate both documents in the Organizer and copy
between them. When you want to keep a template (that is a .dot file) updated
with new styles, copy the styles from the document that has them to a
template and then from the template into another document.
To copy styles between documents, use the following steps:
Step Action
1 Open both documents: the one you want to copy to and the one you
want to copy from. Click either Tools > Templates and Addins or
Format > Style and press the Organizer button in the dialog box that
opens. The currently open document displays on the left and the
Normal.dot (global template) displays, as a default, on the right.
2 You can copy styles in either direction. This example provides directions
for copying styles from the right to the left (that is, directly into the
currently opened document).
If the file on the right is not the file you want to copy styles from, click
Close file. The button changes to Open file. Click Open file and then
browse for the file you want to copy from.
3 Select one or more styles from the document you want to copy from. The
Copy button changes from pointing to the right to pointing to the left.
Click Copy. The styles are copied to the current document on the left.
4 Click Close.
Tips • To display styles for a document in the left margin, click Tools > Options >
View. Under the Outline and Normal options category, enter 1” in the Style
Area Width box.
Note: This only works in Normal View.
23
Numbering Headings and Paragraphs

Heading and This type of numbering is often called “mil spec” because it is used for
Paragraph specifications in military handbooks. It is frequently used in the early phases
Numbering of outlining or organizing a manual or handbook. Unless it is required for
easy reference by your organization, avoid using mil spec numbering in final
documents. They are usually unnecessary with subheadings. In general,
number prefixes detract from the meaning of words in headings and
paragraphs, making it difficult to scan or understand headings and text.
An example of part of a document using mil spec numbering:
Auto-numbering Chapters and Appendixes

Setting Up When you design a document that contains both chapter headings and
Auto- appendix headings, you can use different heading style levels to apply
Numbered different number formatting to each section. For instance, chapter and
Chpt/App appendix heading numbering resembling the following can be defined:
Headings Chapter One: This is the title to the first chapter
Chapter Two: This is the title to the second chapter
Appendix A: This is the title to the first appendix
Appendix B: This is the title to the second appendix
Anytime you change the order of text using an auto numbered style, all text
using the same style renumbers automatically. For example, when you move
a chapter to a new position in a document and update the document, the
chapters automatically renumber.
Once a style is set up to auto number, the number associated with the style
can be used as an updateable cross-reference and can also be appended to
a caption that also auto numbers. For example, in the text “refer to step 1 to
24
learn to…”, 1 is a direct cross-reference to a step. For more information, see

Captions on page 36 and Cross-References on page 31.
To set up a style for a chapter or appendix heading that auto numbers, use
the following steps:
Step Action
1 Select Format > Style. Select a style in the Style dialog box and click
New or Modify.
Note: It is often best to create a new style instead of modifying an existing style
since other writers may expect commonly named styles to behave the same in
all documents. For example, create a ‘Chpt Heading’ style based on the
‘Heading 1’ style and leave the Heading 1 style as is.
2 In the Modify/New Style dialog box, name or modify the style name,
type, the style its based on, and the style to follow.
Select Format > Numbering.

3 In the Bullets and Numbering dialog box, click the Outline Numbered
tab and then click on the style on the bottom right.
This style, selected in the following figure, automatically inserts “Chapter

N+1” or the appropriate text each time the style is used. Following
“Chapter #” you can type the title of the chapter.
4 Click Customize.
In the Customize dialog box (shown in the following figure), make sure
that 1 is selected in the Level list so that this style is a Level 1 Heading.
For a chapter heading:

Type Chapter in the Number format box
25
Step Action
Select 1,2,3,… from the Number style.
Note: In the Number format box, you should see "Chapter 1 " with the
"1" highlighted.
For an appendix heading:

Type Appendix in the Number format field
Select A,B,C,… from the Number style box.
Click OK.
5 In the New/Modify Style dialog box, check the Add to Template

checkbox and click OK.
6 Click Apply in the Style dialog box.
The new or modified style is added to the style list. Each time the style is
used, an additional count is added to the last value so that it auto
numbers sequentially.
Auto-numbering Lists
Setting Up To setup an auto numbered list style, use the following steps:
Auto-
Numbered
Lists
Step Action
1 Select Format > Style. Select a style in the Style dialog box and click
New or Modify.
Note: It is often best to create a new style instead of modifying an existing style
since other writers may expect commonly named styles to behave the same in
all documents. For example, create a ‘Chpt Heading’ style based on the
‘Heading 1’ style and leave the Heading 1 style as is.
26
Step Action
2 In the Modify/New Style dialog box, name or modify the style name,
type, the style its base on, and the style to follow.
Select Format > Numbering.

3 In the Bullets and Numbering dialog box, select the Numbered tab and
then click on the format you want to apply.
The format selected in the following figure automatically inserts “N+1.”

each time the style is used.
5 In the New/Modify Style dialog box, check the Add to Template

checkbox and click OK.
6 Click Apply in the Style dialog box.
The new or modified style is added to the style list. Each time the style is
used, an additional count is added to the last value so that it auto
numbers sequentially.
27
Page Numbers and Page Breaks

Inserting The first page of sections should begin on an odd (or right) page.
Page Breaks There are four kinds of section breaks in Word.
Type When to use it How to insert it

Page break: The point at which one 1. Place the pointer where you want to
page ends and another insert a page break.
begins on a new page.
2. Click Insert > Break or CTRL +
Use it to force a page ENTER.
break at a specific
3. In the Break dialog box, select
location.
Page Break
In Print Layout View, Print Preview,
and in a printed document, text after a
page break appears on a new page.
In Normal view, an automatic page
break appears as a single dotted line
across the page; a manual page break
appears as a single dotted line
marked "Page Break."
Next page: Use it to start a new 1. Place the pointer where you want to
section at the top of the insert a page break.
next page.
2. Click Insert > Break
Next page
Both onscreen and in print, Word

starts a new page at this section
break.
Continuous: Use it to start a new • Place the pointer where you want to
section at the insertion insert a page break.
point.
2. Click Insert > Break
Continuous
Onscreen in Normal view, a section
break displays. In Print Layout and in
Web views, the break is transparent.
Odd page: Use it to start a new Place the cursor after the last text at
section at the next odd the end of the preceding section.
page (typically used to
Select Insert > Break, select Odd
start a new chapter)
Page.
28
Starting on New chapters/appendixes should start on odd pages. To insert an odd page
Odd- break, see Inserting Page Breaks on page 28.
Numbered
Pages
Inserting an Chapter and appendixes should begin on odd pages. If a section ends on an
Even Blank odd page, use the following steps to insert an even blank page between the
Page Before a two sections.
New Section
Step Action
1 Position the pointer at the end of the last paragraph of the last page.
2 Click Insert > Break and select the Page Break radio button in the
dialog box that opens. A new even, blank page is inserted at the end of
the section. If the page numbers are set up, check to see that it has an
even page number.
Changing an To change the page a section starts on from even to odd, use the following
Odd to an steps:
Even Page
Step Action
1 Position the pointer at the beginning of the first paragraph of the first
page.
2 Click File > Page Setup and click the Layout tab. Select Odd page
from the Section Start drop-down list.
Headers and Footers

Headers Headers should include the chapter/appendix title and number/letter aligned
in the upper right corner of each odd page and manual name on each even
page. To add text to or change text in the header, use the following steps:
29
Step Action
1 Click File > Page Setup, click the Layout tab, and select the Different
Odd and Even check box. Make sure the Different First Page check
box is not selected.
NOTE: If you have an existing header, double-click on it, opening

the Header and Footer dialog box where you can modify
the text appropriately. In caBIG™ templates, the odd page
headers are linked to chapter names, so the text should
change automatically as you type in the name. Verify this,
however, to make sure it is working appropriately.
This sets up the document so that the odd page headers are different
from the even page headers.
2 Select the first odd or even page on which you want to include a header.
Click View > Header.
The Header and Footer dialog box opens, the document’s text becomes
unavailable, and the pointer is active in the Header box.
3 If the header text is on the first page of the chapter, then make sure that
the Save as previous button is not selected.

4 Type text so that it aligns on the right side of the Header for an odd page
and the left side for an even page.
Odd page header = [Chapter/Appendix title in Times New Roman, 10 pt]
and [“Chapter/Appendix” number/letter in Times New Roman, 10 pt,
Italic]
Even page header = [Manual Title, Times New Roman, 10 pt]
The following figure shows a header for an odd page.
5 For the first header in a new section, such as a chapter or appendix,
make sure the Same as Previous button is not selected.
Footers Footers should include only the page number aligned in the lower right
corner on odd pages and the lower left corner on even pages.
Page numbers begin on the Table of Contents at a Glance page and number
consecutively with lower case roman numerals to the beginning of the first
chapter. On the Chapter 1 title page, numbers begin at 1, Arabic numeral
format and number consecutively through the last page of the index.
30
To insert a page number in the footer, see Page Numbers and Page Breaks
on page 28.
Cross-References
Using Cross- Use cross-references in end-user documentation to direct users to related
References information that may add to their understanding of a concept but is not
essential to the task at hand. For example, a user should not have to look up
material to complete a procedure.
Start a cross-reference by telling users why they should look elsewhere, not
where they should look. For example, “For more information about UML
modeling, see Chapter 3. “
When citing sources that are not contained in the document, italicize the
source. Place quotation marks around sections and chapter names.
For example, “For more information about cross-referencing, see the
Chicago Manual of Style, Chapter 17, “Indexes”.
Inserting Cross-reference fields are inserted as hyperlinks by default. When you click
Cross- the cross-reference field, Word automatically scrolls to the location of the
References referenced item. You can combine details, such as heading text and page
number of the cross-referenced item, by inserting a two cross-reference
fields. For example, by using two cross-reference fields, you can create the
following, “See Table 7 on page 23”
In documents, attempts should be made to use Word’s cross-referencing

feature to create updateable cross-references.
NOTES:
• Add the page number to a cross-reference only if the
referenced item is not close by in the document.
• If you type or “hard code” a cross-reference, it cannot be

automatically updated.
If the text to be cross-referenced is one of the following types:

• numbered item
• heading
• bookmark
• footnote
• endnote
• equation
• figure
• table
…then use the following steps to insert a cross-reference:
31
Step Action
1 Position the insertion point where the cross-reference should appear and
click Insert > Reference > Cross-reference.
2 In the Cross-reference dialog box, select the reference type from the
Reference type list (for example, Heading or Bookmark).
3 Select the type of text to insert from the Insert cross-reference to: list
(for example, ‘Heading text’ or ‘page number’).
4 Select the item to cross-reference in the For which… box.
5 Select the Insert as hyperlink and Include above/below checkboxes, if
appropriate.
6 Click Insert. The cross-reference is inserted as hyper linked text.
Updating
Cross- Use the following step to update a cross-reference:
References
Step Action
1 Select the cross-referenced text, a section of text containing cross-
references or the whole document and press F9 or click Update Fields
from the shortcut menu.
Cross- Cross-reference text should take on the text of the paragraph in which it is
Reference inserted. For example, if a cross-reference is inserted in a paragraph that is
Styles formatted with Body style, then the cross-reference is also formatted with
Body style when inserted.
Tips Sometimes the cross-reference uses a bookmark. To create a book mark,

use the following steps:
Step Action
1 Place the cursor in the section to be bookmarked, highlight a section or
range.
Note: You can also select text containing cross-references and click Update
Fields from the shortcut menu.
2 Select Insert > Bookmark. In the Bookmark dialog box, enter a name
for the bookmark and click OK.
Note: The bookmark name must contain no spaces.
32
Images
Figure Figures used in the software documentation use the following formats:
Formats in
the metafile – This is the common graphics file format in Windows. This is the
Documenta- format when you copy, then paste a graphic in a Microsoft office program.
tion gif –Used in Word documents that make up RoboHelp HTMLHelp. Also, the
preferred format for images to be inserted into FrameMaker by reference. Gif
stands for graphics interchange format, a bit-mapped graphics file format.
GIF supports color and various resolutions. It also includes data
compression, making it especially effective for scanned photos. These files
end with a .gif extension.
bmp – Bmp files are too large to use them routinely in Word or FrameMaker
documents. Bmp is an image stored as a series of pixels in a format called
device-independent bitmap (DIB). This is standard bit-mapped graphics
format used in the Windows environment. By convention, graphics files in the
BMP format end with a.bmp extension.
eps – Encapsulated PostScript (EPS) is a standard file format for importing
and exporting PostScript files. Save Visio images in this format for importing
into Adobe FrameMaker.
Capturing To capture images , use the following keyboard shortcuts:

Images and/or
Screen Shots Shortcut Result
Alt + Copies image to Clipboard in metafile format. If you do this with a
PrintScreen dialog box open, just the dialog box is captured.
key
CTRL + V Pastes image in Word
Note: To capture images using Snag-It, an inexpensive application obtained

from http://www.techsmith.com/products/snagit/default.asp, see instructions
for that software.
33
Capturing To capture images in FullShot, an inexpensive application obtained from

Images in (http://www.inbit.com/fullshot8.html), use the following keyboard shortcuts:
FullShot
Shortcut Result
CTRL + 1 Screen capture
CTRL + 2 Window or dialog box capture
CTRL + 3 Region capture (use cursor crosshair to enclose region)
CTRL + 4 Title and menu capture
CTRL + 5 Freehand capture
CTRL + 6 Mouse point capture
CTRL + 7 Button capture
CTRL + 8 Command bar capture
CTRL + 9 Auto-scroll document capture
TIP: To make sure captured screen shots do not display Fullshot symbols on
title bar, select Options > Snapshot Button Setup. Turn off all snapshot
buttons. Click OK.
Inserting a To insert a captured screen shot, use the following steps:

Captured
Screen Shot Step Action
1 To capture a screen shot or a dialog box in metafile format, press ALT +
PRINT SCREEN.
2 Place the pointer at the insertion point where the figure should be
placed.
3 Press CTRL + V to paste the image.
4 To resize the figure, press SHIFT + click on any corner and drag the
corner to the selected size.
Tips • If an inserted image is distorted, fuzzy or text or other segments of

original image are lost, select Edit > Paste Special, and select one of the
other listed formats such as “Picture (Windows Metafile).
• A method of easily realigning an image is to select it, then click the

Increase Indent or Decrease Indent buttons.
• As an image is positioned in a Word document, it automatically aligns (or

snaps) to an invisible grid, which helps keep everything lined up.
• To resize an image keeping the same aspect ratio with respect to original
size, click the image to select it, then press shift + place cursor on a
corner handle (it becomes a diagonal two-headed arrow). Drag the image
corner diagonally, making the image larger or smaller.
34
• Most images in manuals should be positioned In Line With Text. If when

you insert an image, it does not align properly on the page and/or does
not respond to your repositioning commands, check to make sure this
layout option is applied by following these steps:
Step Action
1 Double-click the image, or select the image, then select Format >
Picture.
2 In the dialog box, select the Layout tab.
3 Under Wrapping style, choose In line with the text.
4 Click OK.
At this point, you should be able to cut and paste the image exactly where
you want it to be. You can then adjust the alignment as described above.
Picture Style Most images by default have the Normal style applied to them, but this or
other styles may make images difficult to reposition. To solve this problem,
select an image and apply the Picture style to it.
NOTE:
All images should have captions (see page 39). Every figure in the document
should have a cross reference to it inserted appropriately in nearby text.
Tables
Inserting a Steps will depend on whether you have a set of pre-defined tables. To insert
Table a table use the following steps:
Step Action
1 Select Table > Insert > Table.
2 In the Insert Table dialog box, specify the number of columns and
number of rows for the table.
35
Styles Capitalize all the main words in a table heading, but only the first word of a
table column heading.
Table headers should be italicized, bold and centered in the column. You can
use the Style Table Header to assign that style.
Table headers can be shaded with 15% gray. Select the cell(s) that are part
of the header. Select Format > Borders and Shading > Shading tab. Click
on the grey box representing 15% shading and click OK.
The text in tables is spaced as follows:
Select Format > Paragraph.
On the Indents and Spacing tab, enter 3 pts in the Spacing—Before and
After text boxes and click OK.
Aligning When several tables appear on a page, align the vertical borders and column
Tables dividers as closely as possible.
Tips Select the entire table by clicking on the 4-headed arrow that appears at the
outside upper left-hand corner of the table when the cursor hovers anywhere
inside the table.
NOTE:
All tables should have captions (see page 39). Every table in the document
should have a cross reference to it inserted appropriately in nearby text.
Callouts
Using Callouts are used in figures and diagrams to clarify elements and provide
Callouts additional information or instructions.
Callouts in software documentation are usually of two types:
1) Callouts that alert readers to specific details of a screen shot. These

callouts (with no borders) should appear to the left of a screen shot.
Example:
36
Instantiated
objects
Horizontal
dimension
Object Instances
to which
messages
are sent
Vertical dimension
sequence of Figure 0.1
messages
over time
2) Callouts superimposed upon an image are used to illustrate or describe
operations or certain features. For these callouts, the use of a border is
subject to your discretion and dependent on the image being described.
Example:
Inserting To insert a callout, use the following steps:

Callouts
Step Action
1 Insert a figure or diagram.
2 On the Drawing toolbar, select Callouts from the AutoShapes drop-
down list.
Depending on the setting for the callout, select a callout on Callout Line
2 or 4.
3 Position the insertion point where the callout should be and drag the
pointer to adjust its length. In the text box, enter text that describes the
featured element.
4 Position the pointer on the callout’s border and click Format >
Autoshape from the shortcut menu.
37
5 Click the Text Box tab. Enter 0 in the Left and Right internal margin
fields.
Click Format Callout. Enter 0 in the Gap field.
Click OK twice to dismiss the dialog boxes.

6 Align the callouts (for viewer window elements) by selecting all to be
aligned with shift + click, then selecting Draw > Align > Align to right
on the Drawing toolbar.
Callout Styles Callouts in documents use the following formats.
1) For identifying and naming regions of software viewing windows or dialog

boxes, callouts have no border and they are positioned in the left margin
of the page about ½ inch to the left of the left edge of the screen shot.
Text is aligned flush right, leaving no gaps between the leader line and
text.
2) For describing functions and features of panes or screens or software,

callouts are superimposed on the screen shot or image and can either be
bordered or unbordered.
• Callout maximum width should be 1.75 inches. Callout maximum depth

should be 4 lines.
• Unless the callout tag text is a title, the callout text style begins with a
capital letter, followed by all lowercase letters. Sentence-style callouts
end with a period.
• Place callouts far enough apart to be read clearly, and space them
evenly so that a drawing does not look cluttered.
• The text in a callout should be Arial, 8 pt.
• Leader Lines:
o Leader lines should never cross each other.
o When placing a leader, cross as few lines in the image as possible.
o Use multiple leaders when you have one callout that applies to
several objects, but don’t use more than two or three per drawing.
38
Captions
Using The following conventions are used for captions:
Captions • Each caption in a document should have a number that corresponds to
the chapter separated by a period from the number of the figure, table etc
as it appears in the chapter.
o The term “Figure” or “Table” under an image or table is written out in
italicized, Times New Roman: Figure 2.7; Table 5.8.
o Every figure or table should have a reference to it in nearby body text.
o in a cross-reference to a figure, the term “figure” is written out: See
Figure. 2.7.
• Word’s default Caption style should be used to format a caption. The
default style is Times New Roman, italics, font 8. The caption is indented
½ inch from the left edge of the image it describes.
Example:
Figure 4. 1 Agent Class from caBIO Class Diagram
• A caption should have a brief description in sentence style with no ending

punctuation. For example: “Table 1.1 Text conventions used in this manual”.
There are three ways to insert captions in Word:

1) By using a style that is reserved for captions such as Word’s built in
Caption style
2) By using Word’s caption feature: Insert > Reference > Caption
3) By telling Word to automatically insert a caption whenever necessary
39
Setting Up an Captions can be configured to auto number as well as to take a prefix from a
Auto- Heading 1 style. For example, if you have used a Level 1 Heading for your
Numbered chapters, you can set up the captions so that the appropriate chapter number
Caption Style is appended to them.
NOTE:
In the caBIG templates, figure captions automatically

assume the chapter number.
To set up auto numbered captions that take the chapter number or appendix
letter, use the following steps:
Step Action
1 Click Format > Bullets and Numbering and click the Outline
Numbered tab. In the Bullets and Numbering dialog box, select the
Numbered tab and click the format you want to apply (see figure below).
The caption will take on the format that you select. Click OK.
Note: If you want tables and figures to simply take on the chapter numbering of a
document that is sequentially and numerically numbered, click the format
selected in the figure.
2 Click Insert > Caption. Click Numbering and, in the Caption

Numbering dialog box, select the Heading Level that the chapter starts
with (for example, Heading 1), the format (1,2,3 or A,B,C etc), and the
separator (period, hyphen etc.). Click OK. These steps establish the
numbering and format for all captions.
40
Inserting After you set up a caption to auto number with the previous steps, follow the
Captions steps below to insert the caption.
Step Action
1 Click Insert > Caption
2 Select Table, Figure etc from the Label list. This text is added before
the caption number.
Click OK.
The caption is inserted with the appropriate text and numbering. For
example, ‘Figure 1-1’ indicates the first figure of the first chapter and
‘Figure 1-2’ is automatically inserted the next time you insert a figure
caption.
Tips If the figure caption appears on the next page separated from the figure it
describes on the preceding page, do the following:
1. Select the figure caption and then Format > Paragraph.

2. Select the Line and Page Breaks tab and clear the Keep with Next box.
If the figure caption is separated from the image due to a lack of space on
the preceding page, either reduce the size of the image or maneuver the text
on the page enough to accommodate the caption directly under its figure.
Note: Sometimes the image and caption jump to a next page, leaving a big
space on the preceding page. After you clear the Keep With Next box
associated with the caption, this usually causes the image and its caption to
jump up to fill the space on the preceding page.
Creating a PDF from Word

Creating a pdf from a Microsoft Word document is not a simple task, but contrary to what some
may lead you to believe, you do not need third party software to do so.
To create the PDF, you must have a full copy of Adobe Acrobat (not Adobe Reader) installed
on your computer. If you have installed Microsoft Word after installing Adobe Acrobat, you will
not be able to create the pdf. Adobe Acrobat must be installed after Word is installed.
To create a PDF from Word, follow these steps:
Step Action
1 Select Start > Settings > Printers. If the Adobe PDF printer or the
Acrobat Distiller printer does not display among the printers available on
your machine, click Add Printer and during the steps of the Add Printer
Wizard, add either or both of those Adobe Printers. (The printer drivers
should be installed with Adobe Acrobat.)
2 When you are ready to create the pdf, from the open Word document,
select File > Print.
41
Step Action
3 In the Print dialog box, for Printer Name, select Adobe PDF or Adobe
Distiller from the drop-down list.
4 Click the Properties button. In the Adobe PDF Document Properties
dialog box, clear the Do Not Send Fonts to the Adobe PDF button and
click OK.
5 In the Printer section of the Print dialog box, select Print to File. Click
OK.
6 In the Print to File dialog box that opens, navigate to the directory where
the file is to be placed. Name the file, and click OK. Note when you
name the file whether the file extension will be .ps or .prn.
7 Open Acrobat Distiller. (Start > Programs > Acrobat Distiller.)
8 In the Distiller dialog box, select File > Open. By default, the dialog box
lists Postscript (.ps) files. If you printed to a .prn file, you must select All
Types in the Files of Type dropdown list. Navigate to the file, select it
and click OK.
At this point in the process, your pdf is created, and it is placed in the
same directory where your .ps or .prn file resides. You can open your pdf
into Adobe Acrobat. It can also be opened from any installed Adobe
Acrobat Reader.
Tips Review the pdf document carefully, as sometimes errors, such as inserted
blank pages, enter, apparently during the pdf creation.
Adobe Acrobat 7.0 or later allows you to save pdfs as Adobe Reader-
enabled, meaning reviewers can insert comments and edits to the pdf in the
free Adobe Reader. or more information, see Adobe Acrobat Online Help.
• Reviewers can easily add comments or edits to a pdf. For more

information, see Appendix A.
• You can create hyperlinks such as from the TOC to corresponding pages
in the pdf. For more information, see Adobe Acrobat Online Help.
MS Word™ Tips, Tricks, and Troubleshooting

This table contains many helps for using MS Word in technical writing projects.
Topic If you have this problem or Do this …

want to accomplish this…
Microsoft help line # 425-635-7056
Bullets No caps at first word Tools > Autocorrect > Autoformat as you type. Clear
Format beginning of list item…checkbox.
Callouts Align shift + select each; draw>align;
press align to right button.
Callouts Reduce or eliminate gaps Select callout; with cursor exactly on border of callout, select
42

between text and arrow/line “Format Auto-shape” from short-cut menu. Select Text-box tab.
to object For left and right internal margin, enter “0”. Press Format
Callout button. For Gap, enter “0”.
Comments make note for further Insert > Comment
attention
Corrupt documents Spacing and index problems See Margins.
Corrupt document message Word 2000 oand 2003 can repair corrupt documents. Open
appears when you try to Word; select File > Open. Select the document. Instead of
open document. clicking the Open button in the dialog box, click the down arrow
and select Open and Repair.
Cross-references Refer to section of manual For Fig, table or chapter. In place where referenceis to appear
type [“See”] or [For more information, see] then select Insert >
Reference > Cross-reference. Select type and name and
Insert. To update, click CTRL + A (Select All). F9 to update.
Delete To delete large portions of a Save a copy of your document before you begin this. Place
large document from the cursor at the beginning of section you wish to retain. Press ctrl
beginning or at the end + shift + home. Everything before cursor to doc beginning is
selected. Press delete.
Place cursor at the end of section you wish to retain. Press ctrl
+ shift + end. Everything after the cursor to the end of the
document is selected. Press Delete.
Field marks Even with show/hide button Tools > Options > View tab. Under Formatting marks, clear
off, Mark Index field text still Hidden Text checkbox. Hides field text completely
visible
Figure captions mis-numbering Insert > caption > new label>[enter Fig. 1.] (or other chapter
number). OK. OK.
Figures Figure caption appears on Select figure caption, then Format >Paragraph > Line and
next page from figure. Page Breaks, clear Keep with Next. (If figure has left big
space on preceding page, doing this will often cause the image
to jump up to fill the space on the preceding page.)
Figures Inserting caption numbers Insert in each chapter individually if can’t follow multiple
document protocol.
Final draft Order of final polishing 1. Figures and tables in individual files
2. Mark index entries; clean up index
3. Make backups
4. Create long document
5. Create cross references
6. Headers and footers, including page numbering
7. Table of contents
8. Create index
9. Select all; press F9 to update all.
Find and replace Correcting many of same F5, then enter phrase or other item in the Replace tab.
items in document
Formatting/style How to show question mark shift + F1 to show; shift + F1 to turn it off
settings, viewing
43

Go to Finding different chapters Use Outline mode; Level 1 headings. Select chapter. Return to
page layout.
Go to Press F5
Headers and footers Create without a lot of View > Headers and Footers. Open Page Setup dialog box.
headaches
1. Select Different Odd and Even Pages.
2. Deselect Different First Page.
Fore each new section for headers, make sure Same as
Previous is turned off before netering anything.
For Footers (page numbers), Same as Previous should be
turned on.
Index Simple index marking Shift + alt + X. Enter keywords and press Mark
Mark range of text Make bookmark: Select range. Then Insert >Bookmark.
Name and Add.
In Mark Index box, select bookmark, in drop down menu, select
named bookmark. Mark.
Update index Select and press F9.
Tool > Options > Wrap to Window. Then Window > New
“Cleaning up” Window (creates copy of doc; both are open.) Select View >
Normal in each. Reduce size of each and tile horizontally, with
left window just wide enough to accommodate one row of index.
Press “paragraph” icon. Review index for problems in left
window. In right window, find pages and code for problems and
fix them.
Index problems Weird page numbering; mis- Due to corrupt document. (Most formatting is stored in last
placed alphabetization; page paragraph mark.)
# with no keyword
1. Press ctrl + end (cursor goes to end of document)
2. Then ctrl + shift + home (selecting like this selects entire
doc excluding last paragraph symbol.
3. Press ctrl + C to copy.
4. Paste in new Word document.
5. Regenerate the index. Weird stuff should be gone.
Keystrokes Increase font 1 pt Ctrl + ]
Decrease font 1 pt Ctrl + [
Heading 1, 2 or 3 Ctrl + 1, 2 or 3
Repeat previous operation F4
Margins Weird unmanageable Save doc as Webpage. Open Webpage doc. Save again as
spacing in document Word doc (with a new name, in case must return to the saved
doc.) Open new Word doc. Corrupt code making weird spacing
should be gone.
44

Object placement Place wherever I want it to Format > Object, select Layout tab. Select Float over text.
go Should be able to place it where I want to.
Page numbers When inserted page In header and footer (H&F), delete p. # where I don’t want it,
numbers in TOC, one then on first page of TOC, in Insert Page Number box, set up to
appeared on copyright page “start here” and numbering format. Then go into Header and
Footer and make sure “continue here” icon is not selected.
Make sure odd and even pages option is set up. Then click p #
button.
At each new chapter, page At each new section, in (H&F) delete incorrect page number.
numbers start over Make sure odd and even pages are set up properly. In Insert
Page Number >Format, make sure “Continue from previous
section” is checked. OK. OK.
Printing “Manual Feed” (want “Upper Start> settings > printer> paper > upper tray
Tray-automatic feed”)
Shared folders Creating Shared Folder in Select any folder wish to share on the network. Name new
Windows Explorer name if you wish. From shortcut menu, select Sharing… In
dialog box, check radio button for Shared As… Set other
parameters as desired.
Styles Create new styles Type in the text or table in the style you want to preserve
Highlight (select) item
In Style text box, type in style name
With selection and style name both highlighted, press enter.
Verify styles throughout Select Tools > Options > View. In Style Area Width text box,
document in style list in left enter 1”. This only works in Normal View.
margin.
Style Convert styles used in one Open doc with Style you wish to transfer. Select either Tools >
document to another Templates and Addins; press the Organizer button in the
document. dialog box, or select Format > Style and press Organizer
button. In left panes, make sure .doc or .dot with styles you like
is selected. If not, close current doc (in bottom panel) and open
.doc or .dot you want. In right panel, make sure Normal.dot is in
lower panel. In left panel, select Style you wish to transfer, like
Header 2; press To >> button, transferring style to normal.dot.
Close dialog box. Open doc you wish style to be transferred to.
Open same Organizer dialog box. In the right pane, make sure
Normal.dot is in bottom pane. Select Style you wish to transfer,
such as Heading 2. Press << arrow to transfer style to open
document.
Table of contents Formatting text in Table of ctrl + shift + click cursor in spot to correct
Contents
if need to move cursor, select line, then click left or right arrow
key
ctrl + shift + F9 converts TOC to text rather than object
Table of contents Default styles Modify styles as described in Word 2000 book
45

Tables Will not break across pages Select table; In Format > Paragraph > Line and Page
Breaks, de-select Keep Lines together and Keep with Next.
Select table heading, then Format > Paragraph > Line and
heading is separated from Page Breaks, select Keep with Next.
table which appears on next
page
Select row. Then Table > Table Properties, the Row tab.
Uncheck “Allow row to break across pages.”
Cell breaks across pages
Format > Paragraph: Indents & Spacing; 3 pts before and

Spacing of text in cells after (or Zero)
Update TOC and index need 1. Print preview forces update
updating
2. Place cursor in either place and press F9.
Circular Text Box Create a shape with a 1. Draw object using autoshapes
number or letter inside
2. Select Object
3. Select Add Text from shortcut menu.
46
Chapter 5 Using Adobe FrameMaker™
Overview This chapter provides a reference for technical writers using Adobe
FrameMaker™. Because it is such a powerful application, producing clean
final documents, the technical writing group at NCICB uses FrameMaker for
generating large documents such as guides and manuals. It is assumed that
skilled technical writers are familiar with FrameMaker, so the following
section is simply a compilation of tips for using FrameMaker in the context of
creating software documentation. For the most part, it does not provide
complete instructions for creating document elements such as TOCs,
indexes, and applying preferred tags, etc. to these elements. Such
instructions can be found in FrameMaker online help.
FrameMaker™ Tips, Tricks and Troubleshooting

Tech Support Call NIH help desk first: 866-319-4357
Adobe Expert Support: Phone # 800-915-9420
Backup files Creating Once a book is compiled, backup files are created
when you save all of the files in the book. If a working
file becomes corrupted, you lose changes you have
not saved, etc, you can always open the last backup
file for the same doc.
Books Title page Once a book is compiled and updated, if you change
the title page, you don’t need to update the book
again. Be sure and save the edited file, however.
Creating new book Open document.
File > New Book; select Yes or No whether the open
doc is part of new book.
File > Save As; Name and Save.
Finalizing • TOC at a glance – Appendix Name and #; Chap
name and #; Index
• TOC – Appendix Name and #, Chap name and
#; Heading 1; Section heading 2; Index
• To TOCs, import FM Template TOC format;
• Check for widows and orphans in TOC and
index;
• Check all headers; page #s; update unresolved
cross-refs; check order of chapters; check
images in chapters; buttons intact?
47

Callouts Moving Press CTRL + CLICK on text box border, selecting the
text box. Press ALT + ARROWS to move selected box.
Click on lines to select them. Press ALT + ARROWS to
move lines or grab handles at ends and drag them to
new location.
Inserting Create text boxes from the Tools palette first, correct
the size, alignment: Click on the Text icon, draw text
box. Type text in box, then select text and apply
Callout paragraph tag. Stretch boxes for position and
size as needed.
Aligning text Reduce size of text box on right side, moving text to
extreme right of box.
Change Bars Change bars mark in the left Format > Document > Change bars; Check
margin where changes are Automatic Change Bars; select color (I use Red);
made in a document click Set.
Be sure and remove change bars before creating final
pdf.
Remove Change Bars Open dialog box; check Clear All Change Bars
Chapter title Order to apply Paragraph tags Must be done in this order: Chapter, press Enter
(moving to new line); Chapter number, press Enter
(moving to new line); Chapter name
Character Designer Creating new In Commands, select As Is; Specify the characters;
Commands > New Format—enter name, click
Create; click outside dialog box, then select new
name from drop down menu; click Update All
Convert Word docs to FM 1. Delete Word TOC
2. Remove headers & footers
3. Remove paragraph Select all; press CTRL + Q
overrides
4. Remove tab characters F5: then Find > Special > Tab character; Replace
with nothing
5. Remove character overrides Select all; press CTRL + SPACE
6. Find and replace styles with Where not known, replace with Body text.
style names used in FM
H2 to H1
H3 to H2
H4 to H3
H5 to H4
normal to body text
body text indent to body text
bulleted or bulleted text to bullet
6. Delete bullets must be done individually/manually
7. Tables remove merged cells
8. Copy Word doc
9. In FM, paste Edit > Paste Special > Rich Text Format (otherwise
text is embedded and unavailable for modification)
48

Cross-references Insert
Special > Cross-reference
Xrefs to figures: Select Caption paragraph tag;
Select Figure # format. Click Replace.
CTRL + ALT + CLICK on cross reference takes you to
reference.
Update Edit > Update references. In dialog box selection
update all cross references option.
Unresolved X-references Edit > Find > Unresolved cross-references
Edit Undo/Redo Edit > Multiple Undo > Undo or Redo
Undo = CTRL + Z
Redo = CTRL + Y
There is only one undo in FM.
E-mail links Activating an e-mail link within Select the e-mail address typed in the document,
a document then click Special > Hypertext. Select Go to URL
and enter “Message URL mailto:<e-mail address>”
En dash Consecutively: CTRL + Q; SHIFT + Q
Em dash Consecutively: CTRL + Q; SHIFT + P
Find and replace Find and change a word Edit > Find/Change; select in Find drop-down menu
character format to e.g. type and text to be found; In Change drop-down
italicized menu, select To character format; in dialog box that
opens, specify new format to be applied to found text
Footnotes Formatting line not applied Select some of footnote text and apply Footnote tag.
Numbering: Footnotes start For each chapter, in Book file, select Numbering
with #1 on each page where from shortcut menu; on Footnote tab, select options
they appear. to continue page numbering where it’s appropriate.
Graphics Call-out with border Draw rectangle and move text box on top of it. Click
None for fill of rectangle. Select Set Pen Pattern,
and click black solid block. Change color to black.
Return to Fill, and click on grey solid block. Fill
becomes white.
Header Creating same header (like Create the header in one of the chapters. Then in the
book title) in several chapters book file, select the chapter(s) the header is to be
at one time transferred to. Select File > Import > Formats.
Select the source chapter file, In the Import Formats
dialog box, leave checked the formats you want to
transfer. (The header is a Variable Definition.) Click
Import.
Transferring header to other See Tags > Transferring tags using import in this
docs or chapters document. Header formats in the Import Formats
dialog box is a “Variable Definition.”
49

Header (cont’d) Editing a header View > Master Pages. Double click on existing
header, opening the Variable dialog box. Click on
Edit Definition. If adding Character tags, click in
position to start tag and click on the tag. When ending
tag, click on <default font>.
Example: <emphasis> Vector <emphasis><bold> NTI
<default font><emphasis> for OS X <default font>
User’s Manual. Ends up looking like this: Vector NTI
for Mac OS X User’s Manual.
Appears on first page of Follow instruction described under “Page Layout”.
chapter (incorrectly) Create, then import template from corrected chapter.
Hypertext link Testing In editable document, CTRL + ALT + click on link.
Index Inserting/Updating Open all chapters in book; Select Add > Standard
Index. After specifying marker types, click Add, then
Update Book in next dialog box.
Listing in TOC Type “Index” for title in Index. Then apply Index tag to
the title. Make sure “Index” is included when creating
TOC.
Images Aligning Turn on grid lines. Select View > Options to set grid
line size. Then press Alt + arrow key to align to grid
as you want.
Create anchored frame Select existing anchored frame; copy; paste; delete
image in pasted frame; paste new image.
or
Place cursor where anchored frame is to go. Select
Special > Anchored Frame.
Cropping image Create Anchored Frame: Special > Anchored
Frame; Click New Frame; select frame; Edit > Paste
copied image into frame; select frame border and
drag handles to position where image is cropped
appropriately
Resizing image Pressing shift while re-sizing keeps image
proportional
Positioning image in frame Select object + ALT + ARROW
Small icon image blots out text With cursor in problem paragraph, open Paragraph
in line above Designer; on Basic tab, clear the Fixed checkbox
under Line spacing. Click Apply [to Selection]
Inserting .gif files image by Note: This is the preferable way to include images in
reference a FM document. If simply pasted in, the files become
much too large.
Insert Anchored Frame. Select frame, then select File
> Import > File. Locate file and click Import. Select
DPI (start with 150) and click OK. Press SHIFT + DRAG
at corner to enlarge image. To move to desired
position, press ALT + CLICK arrow button.
Once images are inserted by reference, don’t change
path or FM will not be able to find the images.
Rotating image Select, then select Rotate from the shortcut menu.
50

Images (cont’d) Inserting Visio images In Visio, save graphic as .eps file type. Insert into FM
file by reference.
If inserted .eps file appears only as gray box, when
saving in Visio in Filter Setup dialog box in TIFF
preview section, select 8-color radio button (this
saves the .eps file with 8-bit TIFFpreview) then re-
import into FM file.
This maintains graphics exactly as they appear in
Visio. (When embedding objects as Visio objects, line
format was not maintained when pdfs were created.
This solves the problem.)
Image goes to next page, Click View > Text Symbols.The anchored frame for
staying with following figure, the second figure (e.g.figure 5.15) was sitting at the
leaving a huge white gap on end of the caption for the first figure (e.g. figure 5.14)
previous page. and was keeping the figures together. Place a return
after the first figure caption. That moves first figure to
previous page and pushes second figure onto the top
of the “second” page. Note that the anchored frame
symbol is right at the top of the second page. To
reduce the amount of space above second figure at
top of page, adjust the font to the smallest size
possible at the top of the second page.(7pt). (Enter a
few a's in the space so you can see it. You can erase
the a's). That gives you a smaller amount of space at
the top of a page when you start that page w/ a
figure. you could also use a smaller font than
whatever 'Body Text' is designed in.
Text wrapping Select object; Graphics > Runaround Properties
Keystroke shortcuts open Goto box CTRL-G or click on status bar where # of #; enter #;
press enter
activate hyperlink alt + ctrl + click on link
doc must be locked first
lock/unlock document Select the file in the book window. Press ESC + SHIFT-F
(1x), then release shift and press l + k (in that order);
(read-only mode) to unlock, repeat the same procedure. May need to
be persistent in doing this. (See pg. 550 in FM book.)
apply formatting to text F-9
refresh screen CTRL + L
Hard return SHIFT + ENTER
Open Find/Change dialog box CTRL + F
Open Character Designer CTRL + D
Open Paragraph Designer CTRL + M
Select line ESC + H + L

Select word ESC + H + W
Select sentence ESC + H + S
Select paragraph ESC + H + P
Select table CTRL + 3X
51

Keystroke shortcuts (cont’d) Select table column CTRL + 2X
Small caps CTRL + E
Nudge ALT + ARROWS (such as changing placement of

superscript)
Go to last page SHIFT + DOWN ARROWS
Select table row CTRL + 2X on divider bar
Open Table Designer CTRL + T
Margins/Tabs Position of margin symbols Top arrow = 1st line indent

Bottom arrow = hanging indent/ = 1st tab stop
Position of tabs Drag from toolbar to position below ruler
Modifying Double-click on tab symbol; opens Edit tabs dialog
box
Numbered lists Begin numbering at 1 Paragraph tag Numbered1
Consecutive numbering Paragraph tag Numbered <n+>
Numbering of chapters, X- Inconsistencies in After chapters are lined up as you want them in a
refs, etc. Book File, select the chapters you want to change or
verify numbering for; from short-cut menu, select
Numbering. In dialog box on Chapter and Page
tabs, make sure selections are what you want. For
instance, radio button to “continue from previous
document”, etc.
Pages Too many pages in a document Usually when you save a document, the extra number
of pages is eliminated automatically. If not, select
Special > Delete Pages. Specify in the dialog box
the pages to be deleted.
Page layout Chapter title position incorrect; A chapter always opens to a second page; with
header where it shouldn’t be chapter open, select Format > Page Layout >
Master Page Usage. In the drop-down menu, select
First, then click Set.
Landscape Format > Customize layout > Rotate page
<direction>
Text on page starts lower than Format > Page Layout > Master Page Usage. In the
wanted (like appears on first Use Master Page field, select Right/Left option.
page of chapter). Click Apply.
Heading at bottom of page; Add page break: Select Special > Page Break.
move to top of next page.
To delete such a page break: Put the cursor at the
beginning of the heading. Reapply the Heading tag
from the paragraph tag menu. That removes the
override from the heading, and it will move back to
the previous page or wherever it fits best in the text.
52

Page layout (cont’d) Images or text superimposed 1. At the end of the last “good” page, insert a new
on other text; text unreadable page, Special > Add disconnected pages(s).
2. Copy and paste the text you want to save on the
new page.
3. Insert images on new page.
4. Select problem page(s) to be deleted (Special >
Delete Pages) and click OK.
5. Resize doc (to 25%) so can see all affected
pages.
6. Check the flow of the document by placing cursor
on last good page, select Edit > Select All in
Flow.
7. Disconnect the last good page from its following
pages: Select last text frame before the problem
(Ctrl + click on text frame border); select Format
> Custom Layout > Disconnect Next.
8. Select text frame on last good page, then Ctrl +
click on text frame on next page (FM
“remembers” first selection, so you have a
multiple page selection).
9. Select Format > Customize Layout > Connect
Text Frames. Do this, then check the doc flow.
Repeat the connect text frame process until all
pages in doc/chapter are connected. Re-check
the flow to verify.
Text runs off the page; hidden 1. Add disconnected page after the last good page:
on next page. Special > Add disconnected pages(s.
2. Reduce page size (% zoom) to perhaps 25% (so
you can see more than one page.)
3. Select the text frame (ctrl + frame around entire
page) of the last good page and select at the
same time the new page (ctrl + click).
4. Select Format > Customize Layout > Connect
Text Frame. The [hidden] text should advance
onto the new page.
Page break Page break cursor position The entire paragraph containing the cursor moves to
top of following page, if that is the selected option in
Page Break dialog box.
Page numbering Add page count “1 of 3, 2 of 3, On a Master Page, click in the header or footer.
etc.” Type in the Word Page
Go to Special > Variable and select Current Page;
click Insert.
In the header or footer, type in the word of
Go to Special > Variable and select Page Count.
Click Insert.
Paragraph Designer Caution! Do not select Paragraph tag from drop-down menu
and Update All. This updates paragraph tag, but
doing it this way can cause problems.
53

PDF Creating .ps file Select File > Print Book. Check the Print to File
checkbox. In the pathname box, the path must be
less than 31 characters in length or ps file will not be
created. I created a folder called “Test” on my D:\
drive. Type in (or copy/paste) the name of that that
folder, plus name of pdf. Example:
D:\test\Macbook.ps. Click the Printer Setup button
and select Acrobat Distiller.
PDF Bookmarks In the Print dialog box, click the PDF setup button
and check the Generate PDF Bookmarks on the
Bookmarks tab for the bookmarks to appear in the left
pane of a pdf. Move Paragraph tags from one pane
to the other for inclusion in the bookmarks. Click the
Set button.
Creating .pdf from a .ps file Open Acrobat Distiller. Click File > Open, browse to
the .ps file you have created, select it and click OK.
Follow the directions for naming and selecting
destination for the .pdf file.
Automatically generated links For links to appear in the pdf, in the Print Book dialog
in pdf box, be sure and check the Generate Acrobat Data
checkbox. Links must be present in the FM TOCs for
them to be automatically generated in the PDF. To
check the links, in an open TOC, press CTRL + ALT,
and left click on one of the chapter heading. If the link
works, the chapter referred to will open. If they don’t
work, update the TOC(s): select Edit > Update. If
they still don’t work in the TOC, delete it from the
book and recreate it.
Troubleshooting inability to Select Start > Settings > Printers. Select File >
create a .ps file Server Properties. On the Ports tab, see if there is a
port titled FILE:. If not, click Add Port, then New Port
in the next dialog box. Type in FILE: and click OK.
Describe port as Print to File. Now in the Print dialog
box from FM, when you select Print to File, the .ps
doc should be printed.
Set up pdf review for Adobe Two methods (both in Acrobat 7.0 Professional:
Reader 7.0 users.
1. Open pdf in Adobe Acrobat 7.0 Professional.
2. Click Send by email for Review on toolbar.
3. Step through the Wizard. Select file, designate
reviewers.
4. Click Customize Review Options button. Check
Allow Users of Free Adobe Reader 7.0 to
participate in Review button.
Or
Click Comment > Enable for Commenting in
Adobe Reader.
Reference pages Store frequently used graphics, View > Reference pages. (See p. 20-4 in training
text and images materials for adding reference items.)
54

Sidewords Note: or Important: Place text that comes after this word on next line.
Then select sideword and apply Sideword. Select the
following text (now appearing on same line) and apply
Paragraph tag, such as Body Text. Sideword is NOT
in a column.
Space “Non-breaking” space: space CTRL + space bar (with the text symbols turned on, it
between text where just a looks like a square U)
space bar doesn’t enter it
Standard templates Review canned templates File > New > Document; Click Explore Standard
Templates; click templates in left-side lists
Superscript Changing placement of Select superscript text and press ALT + arrow keys.
Symbols Inserting To insert →: CTRL + Q , then a period. If something
other than a symbol displays, then select it, and apply
Symbol font style to it.
Insert ™ : CTRL + Q; SHIFT + *
Insert – : CTRL + Q; SHIFT + P
Insert o: CTRL + Q; SHIFT + [
Tags Copy/Paste new tag from other Copy text using the special tag from another chapter.
doc Paste it in current doc. 2X click to select it. Open
Character Designer. In that menu, click Apply. Apply
to Catalogue? Yes. Then delete the pasted text
(unless you want to keep it.)
Update a lot of pasted text with Make sure new text has same tag name, even though
existing tag. * in front of it says needs to be updated. Place cursor
in “like” (updated) text, open Paragraph Designer,
select the tag to be applied, click Update All. In
intercept dialog box, select “Remove Overrides.”
Transferring new tag from other Open chapter/doc having tag you wish to forward and
doc using Import the doc you wish to transfer to. Select File > Import >
Formats. Select what you want forwarded.
55

Tables Importing tables from Word Steps in formatting imported tables in FrameMaker:
1. Paste Special to paste in FM document.
2. Pull table up to end of previous line. (Put cursor
in line above and hit Delete.)
3. In the table, select Table > Table Designer.
Select Table > Column Header. Click Apply.
4. Position cursor in top row of table. Select Table >
Add Rows or Columns. Click Add Row to
Heading in the list. Click Add. This gives you the
running table header across pages.
5. Copy the text from the old header line into the
new header line.
6. Delete the old header line, using Edit >Cut.
7. Assign the correct paragraph tag (Table Header
to the new heading cells.
8. In the caption line, apply the Table Title
paragraph tag. Copy the old title text and paste it
into the new title line underneath the table.
9. Delete the old title line.
10. For the table cells, select them all and apply the
Table Text 4 paragraph tag.
11. Add the Continued variable. Position cursor in
the caption the first place where it appears—first
page of the table. (If your cursor won’t click the
caption, you’re not on the first page of the table.)
At the end of the caption words, click Special >
Variable. In the dialog box, scroll down and
select Table Continuation. Click Insert.
Selection techniques Row: drag across or ctrl + point on column border +
double-click
Column: drag across or ctrl + point on row border +
click or double-click
One cell: ctrl + click in cell
Entire table: ctrl + triple-click or Esc + t h t
Showing/hiding table Table > Custom Ruling and Shading. Configure
rulings/borders Custom Cell Ruling section.
Open Table Designer shortcut CTRL + T
Centering text/images in cells Select cell(s) with text to be centered. Open
Paragraph Designer. On the Table Cell tab, in the
Cell Margins, leave From Table Format, plus. In the
next text box, enter ~ 30. Click Apply. Modify until
positioned where you want it.
Table Position Position: when imported, some tables are centered;
place cursor in table, then open Table Designer
(Table > Table Designer); select Format B, then
Apply to all. All tables should then be repositioned at
left alignment.
56

Tables (cont’d) Start on previous page after If Delete right after anchored frame does not work,
anchored frame place the cursor before the anchor and press Delete.
The solution to this problem lies in working with the
text that comes before the table.
Add/delete Continued in table On first page of table, place cursor after the caption to
caption on second page be continued. Select Special > Variable > Table
Continuation. Click Insert
To delete the Continued variable (if added more than
once, for instance), highlight it on the first page of the
table, and click the Delete key.
Caption Place cursor after table. Click Caption tag.
If a Figure caption or bold caption appears when table
is repositioned, in Paragraph Catalogue, click Table
Title. Then type in additional caption text. Delete
caption that appeared when doc was imported.
To eliminate a caption, open Table Designer. In the
Title Position section of the Basic tab, select No
Title.
Add new row to table Cursor in row above new row, CTRL + ENTER
Table runs off page to the right Select Table > Resize columns; rescale to width
totaling 6.5
Start table on previous page In Table Designer, change Orphan rows to “3” or
anything greater than fits on the page. In Paragraph
Designer, on the Pagination tab, uncheck Keep with
Next. See also “Start on previous page after
anchored frame”.
Paragraph tag descriptions Figure: table for figure; has caption below
Format B:
Table column header: table with 2 header rows
Table Header: table with 1 header row
Table no header: table with no header row
Removing Table Title cell Open Table Designer. On the Basic tab, open the
drop-down menu under Title Position. Select No
Title.
57

Tables (cont’d) Table header repeating on a If a header row is defined in a table, then it
new page automatically repeats on a new page in FM. It
appears to be a two part process: define the header
shading in the table designer and add the heading
row when the table is inserted or thereafter. Also
when a new table is added (Table > Insert Table),
there is the option to add one or more header and
footer rows in addition to body rows and columns in
the dialog.
For a table caption: Click in the table and open Table

Designer. Under the Basic tab, under Title Position,
select Above Table (or wherever you want it).
For a heading, if the table doesn't already have it, you

have to add a heading row so that it repeats over
page breaks. Click in the table, choose Table > Add
Rows or Columns. In the dialog box, select the radio
button for row and then use the pull-down menu to
select To Heading.
Text Headings/captions, fine in Try other printer. Install new printer driver.
electronic document, are
gibberish when printed out.
Boxing Text 1. Insert an anchored frame.
2. Insert a text box from the drawing tool inside the
anchored frame.
3. Copy text into the text box.
4. Draw a box around the text box with the drawing
tool.
Doing this this way, the text + box will always stay
together.
TOC Updating Imported formats (including leader dots) do not
appear until you update the TOCs again.
Adding new tags to existing Select TOC in the Book File, right click and select Set
TOC up TOC. Add new tags and regenerate the TOC.
Dot leader problems If page number aligns to left, rather than to right,
place cursor in front of pg # and press the tab key.
or open Paragraph Designer. Place the cursor on a
“good example” in the doc. On the Basic tab, note
what setting #s are in the Tab Stops box. Then place
cursor on problem line. In Tab Stops section, click on
problem # and edit. Type in correct # and other
“good” settings. Click Apply.
Creating Include Appendix name, Appendix number, Chapter
name, Chapter number, Index tags, for TOC Glance
and additional Headings (1 & 2)
TOC text aligns to the right View > Text symbols. Increase the % zoom. Go to
heading text in chapters. See if text symbol appears
in front of heading text. (These seem to be holdovers
from converted Word documents.) Delete text symbol
and update book.
Problems in creating TOC must be created in current book; cannot copy a
TOC from another book and paste the file in this book
58

Tracking Changes Select Format > Document > Change Bars. In the
Change Bar Properties dialog box, select the position
and color Red. Click the Automatic Change Bars
checkbox, then click Set. You must do this in every
FM document that you want change bars turned on
in.
When you make changes, a red, vertical bar appears

in the margin indicating a change was made in that
paragraph at that location.
When finalizing the doc, remove the change bars or

they will show up in the pdf. Open the Change Bar
Properties dialog box again, and select Clear All
Change Bars checkbox. Uncheck the Automatic
Change Bars box so further changes are not
recorded. You must do this in every FM doc.
Widow/Orphan Text or caption moves to top of Put cursor in caption. Open Paragraph Designer. On
next page when don’t want it Pagination tab, under Keep With, click on Previous
to. Page. Click Apply.
Undo/Redo See under Edit …
59
60
Creating Online Help Chapter 6
Chapter 6 Creating Online Help
Overview This chapter outlines an effective online help project and describes the
essential elements of a well designed online help.
Frequently Asked Questions (FAQs) about Online Help
What is Online help is topic, procedural or reference information accessed using a

Online Help? computer. Online Help is designed to give assistance in the use of a software
application or an operating system. When help topics are opened directly
from and describe a viewer or a specific dialog box, they are said to be
context-sensitive.
When is Online help should offer quick, complete descriptions of problem solutions. It
Online Help is generally consulted when computer users encounter a problem in the
Used? midst of their work, often as a last resort when a user is “stuck”. Online help
is used to help a user diagnose and treat a symptom, not learn a subject.
It is important to remember when generating online help that often when

users turn to online help, something has interrupted their work flow and they
may be frustrated, upset or worried. Online help allows them to read, learn,
browse or get an answer and get back to work. The less online help can
seem like an intrusion, the better.
How is Online Online help differs from other forms of software documentation in the
Help Unique following ways:
From Other • Context—Online help is consulted when the user is using the software,
Forms of usually in the midst of performing online tasks.
Software • Purpose—Online help is used to solve a current problem or to give
Documenta- directions for tasks in a workflow.
tion? • Audience—Online help is written for the users of the software from
which online help is accessed. Online help is never read for relaxation or
entertainment.
• Access—Users don’t have to buy, store and hunt for printed materials.
• Usability—Online help is written to be used quickly. Inter-topic hypertext
links and jumps make it very easy to find information, to follow a thread
of logic or interest.
61
Elements of Online Help

Elements of online help should be simple, concise, and easily navigable. The following tables
summarize the elements of online help.
Table of The Table of Contents for an online help project displays a hierarchical list of
Contents topics, forming an outline of the project. In an online help TOC, related topics
(TOC) are usually grouped into “books” or other designated sections.
In designing your TOC, you should group topics as a user would expect to
find them. You should use a fairly shallow hierarchy, avoiding too many
levels, thus reducing the number of steps needed for finding information in
online help.
Online Help The body of an online help project consists of many topics, each of which
Topics answers one specific question or covers one topic. Each topic should be
unique and independent of other topics, although it can be closely related to
other topics to which it refers through hypertext links or Related Topics
buttons.
Keep topics brief, generally keeping the text readable in one viewer window.
Although there may be exceptions to that, you should consider dividing a
long topic into smaller chunks (topics) than you would for a printed manual.
People, for the most part, don’t read long passages on a computer screen.
On the other hand, leave topics in chunks big enough to be meaningful as a

stand-alone topic.
A topic should be able to be accessed five or six ways—through the TOC

topic file, through several different references in the index, through
generating a word search, through hyperlinks and/or See Also or Related
Topics buttons in other topics.
Index The online help index should generally include two or three references to a
single topic. Some help authoring software can generate an index
automatically for the project. You need to check that index, in any case,
because it is usually generated only according to the topic title, and that may
not be the best way to reference the topic. The advantage of creating the
index yourself is that you can bring any number of topics into an index
reference.
For general guidelines for creating an index, refer to the section Indexes on
page 16 in this Technical Style Guide.
62
Hypertext Electronic hypertext links are inter-topic links or “hooks”, showing

Links relationships between topics. They allow the user to quickly and easily move
around at will, building easily navigable paths through the material. They
encourage the user to jump from one topic to another, following a thread of
logic or interest.
You can design hypertext links to open pop-up boxes that display brief
information relating to the feature from which they are opened.
You can also add See Also or Related Topic buttons to your online help
topics. They are designed to display a list of associated topics when a user
clicks on one of the buttons.
Browse Browse sequences allow users to move forward and backward through a
Sequences series of topics arranged in a specific order. Authors define the order based
on what they want users to accomplish or know after browsing through the
topics and reading the content.
In your help authoring software, you should discover the methods for defining
the browse sequence. Some software can create the browse sequences
automatically based on the TOC, limited by levels of the TOC hierarchy you
define. Alternatively, you can set the browse sequence manually.
Some online help authoring software creates “bread-crumb” trails through

topics, allowing you to easily retrace your steps through your topic path.
Online Layout and Format

Format and layout features have a major impact on the usability of your online help project. The
format and layout guidelines are different for online help than they are in other electronic or
even printed documentation. When creating online help topics, be sure and use the software
feature that allows you to preview topics so you can view how the finished topics will appear to
online help users.
Formatting You can maximize the effect of online help formatting and layout by following
and Layout these guidelines:
• Increase the line spacing and blank space beyond the convention for
paper manuals. Leave plenty of white space around the information in a
topic.
• Left justify text.
• Keep lines short.
• Use a basic, simple interface: it should be easily accessible, navigable
and searchable.
• Downplay fancy formatting and layout.
• Keep in mind that screen reading is difficult
63
Software for Creating Online Help

It is recommended that you use a mature software application for generating your online help
project, one that can easily generate topics, the TOC, index, hypertext links, popups, and
compile the project in preparation for integrating the project into the application your team is
developing.
As of early 2006, there is no open source software available for generating a mature online help
project that can be integrated easily with software. Authors can use an HTML editor for
generating content manually in HTML format, if that is what you prefer.
Commercial • Macromedia’s RoboHelp has set the standard for authoring applications
Online Help in the past 10 years, but changes in its production may necessitate
Software considering other alternatives.
• MadCap software creates Flare help authoring software into which
RoboHelp projects can be integrated, if that has been your software of
choice in the past. MadCap corporation was founded by former
developers of RoboHelp software.
• Quadralay WebWorks is a reliable, stable authoring application that
provides an added feature allowing you to “single-source” your content
from either Word or FrameMaker. This means you generate content only
once, generating both the electronic documentation and online help from
the same source files, thus saving your technical writer much time.
• EC Software Help & Manual
Commercial software programs are available for generating cross-platform
online help projects.
Generating the Online Help Project
Analyzing As you design your online help project, it’s important to keep the target
your Target audience and the context in which the project is used clearly in mind.
Audience
• Place self in mind of user.
• What hardware will the user be using?
• How will the online help be accessed—in a browser, or in the
application?
• Do you need to create cross-platform help?
• Remember the purpose of online help—usability and ease of access
What to As you determine what to include, your focus should be on “need to know”
Include in information rather than “nice to know”.
Help
As you create your online help project, begin your design “from top down”. In
other words, start with the TOC, which gives you an outline for the project.
64
Once you have the TOC, build the project “from bottom up”, writing topics
that correspond to the outline. After you add topics to the TOC sections, it is
easy to rearrange them later in any order you want.
You can use an electronic or hard-copy manual or guide as a source, but do

not just paste text from a manual into online help without modifying its
content. Analyze the best way to use the material from an online help
usability perspective an edit it accordingly.
You should Include procedures, troubleshooting, and reference material. Use

screen shots sparingly. Remember, the user is already on the computer and
can easily visualize what you describe by returning to the software viewer.
An image should be used only when it conveys essential information.
If you are single sourcing your files, keep in mind as you write, the context of
both the electronic documentation and online help topics. You can even
insert conditional text in your source files so text is designated appropriate for
the selected output, electronic documentation or online help.
What to Leave Leave the following material out of your help project:
Out of Help • Lengthy overviews
• Elaborate introductions
• Installation directions
• Summaries
• Long explanations of steps
• Information the user already knows
• Hand-holding tutorials
• Marketing hype (and language)
Hypertext When adding hypertext links of any type to a topic, you should consider if the
Links link is logical, if it is a link a user would understand and consider important.
Each help authoring application features its own methods for creating
hypertext links. For the most part, links should be highlighted in single words
or short phrases. The processes for activating the links can be very simple,
such as dragging topic titles to the highlighted text. See Also or Related
Topics buttons can often be equally simple to link, dragging topics to the
button under which they are to be listed in RoboHelp or applying a Related
Topics style or tag to be applied in WebWorks ePublisher.
A Context- Context-sensitive help provides information about what users see inside
Sensitive Help applications—details about fields and controls in dialog boxes, explanations
Overview of messages and descriptions of windows and screen objects.
It is called context-sensitive because each topic is called by the application,
65
providing information relevant to the task the user is trying to accomplish.
There are two kinds of context-sensitive help:

1. Window-level help usually explains a dialog box, control, button or
other part of an application from which the help topic is opened. It is
implemented from a help button or menu option, a right-click menu
option or sometimes an F1 key. This kind of help opens in a topic
window.
2. What’s This help usually explains a specific field, button or option in a
dialog box or application. It is generally implemented from a question
mark button (called a What’s This button) on a tool bar or in a dialog
box. When the user clicks the button, the cursor changes to a
question mark. The user can then click this “interrogative cursor” on
the item they want help with, and a popup opens with brief descriptive
text describing the feature or text from which it opens.
Creating Four components allow context-sensitive help to function.

Context -
Sensitive Help The developers are responsible for the first two:
1. The application making the help calls.
2. The application help engine
You, the online help author, are responsible for creating the remaining two:
1. The map file
2. The topic text file
It is essential that you work closely with the application developers to

determine the most efficient and successful way to create and implement the
context-sensitive links, (as well as the online help as a whole). To implement
the context-sensitive help, you must identify for the developers the
application features that must be mapped to topics, the mapID titles or
mapID#s to which they must be linked and the corresponding topic titles.
The following example displays how this information was recorded to be

shared with developers for one application. You can determine what methods
your help authoring tool uses to create mapID numbers. Developers can
choose to use the mapID numbers or mapID titles or both to implement the
context-sensitive links.
66
The following sequence of events is necessary to implement context-sensitive help. The

process is illustrated in Figure 6. 1.
Step Action
1 The user causes the application to send a Help Call to the help engine
by clicking a Help button, selecting a Help menu option or prompting the
call in whatever manner the developers have designed.
2 The help engine uses the information from the help call to obtain
information from the Map File.
3 The help engine uses the information from the map file to obtain the
popup text or topic text from the topic text file.
4 The help engine uses the information from the topic text file to create
and display the popup or a text topic.
67
Map IDs
MapID 31 login_page_help
Map ID 46 add_user_help
mapID 49 screening_model_help
2. Retrieve MapID
Application
3. Identify associated topic file
1. Help call
4. Display topic
Help Engine
login_page_help=caMOD Login Page

add_user_help=Adding a New User
screening_model_help=Screening a Model
Topic Titles
Figure 6. 1 The process for calling and displaying context-sensitive online help topics
WARNING!
Inform your developers that they should never rename online help output
folders or files. This can introduce problems that may interfere with
successfully integrating online help.
Finalizing Online Help

Once you have completed your project, you must compile it and test it. Compiling the project is
determined by the help authoring software you are using. This produces the few essential
project files you must send to the developers so that they can include them in their final software
system. Check your help authoring software system for details.
68
Testing the Once you have been notified that the online help project is integrated into the
Completed software build, you should test its implementation.
Help Project • Check internal hypertext links.
• Check the See Also or Related Topics buttons.
• Check the display and resolution of all images.
• Check the TOC.
• Scroll through the browse order of topics.
• Verify index links.
• Check the context-sensitive links from the application itself.
How can • Keep the audience in mind

Online Help • Recall when and why people press help button
Be Made Most
• In the application, make it obvious how to access help (Help buttons,
Effective?
What’s This button, F1 key, Help menu options)
• Insert hypertext links generously and appropriately
• Implement logical context-sensitive help
• Tell users about help at every opportunity: training, tutorials, include help
options on application menus
69
Style and Mechanics Chapter 7
Chapter 7 Style and Mechanics
Overview This chapter provides a reference for style and mechanics issues.
Bibliographies
Citing Books Author’s name (last name first for the first author, first name first for
additional authors). Title, including subtitle. Additional information about the
book including editor’s or translator’s name and volume number. Edition
number, if not the first. Facts of publication: Place, publisher, date, etc.
Example:
Kimura, M. (1983). The Neutral Theory of Molecular Evolution. Cambridge

Univ. Press, Cambridge.
and
Dayhoff, MO, Schwartz, RM, and Orcutt, BC (1978). A model of evolutionary

change in proteins. In Atlas of Protein Sequence and Structure, M.O.
Dayhoff, ed. (Washington, DC:National Biomedical Research Foundation),
345-352.
Citing Printed Author’s name(s), (year). Title of article. Title of Periodical. Volume, page
Magazine and numbers. (Molecular Biology of the Cell journal format)
Journal
Articles Example:
Rose, GD, Geselowitz, AR, Lesser, GJ, Lee, RH, and Zehfus, MH (1985).
Average area buried on transfer from standard state to folded protein.
Science 229, 834-838.
Citing Generally provide enough information so the user can find the source.
Computer Examples:
Programs or 1. Cancer Bioinformatics Infrastructure Objects (caBIO):
Websites http://ncicb.nci.nih.gov/core/caBIO
2. Object-Relational Mapping articles and products: http://www.service-
architecture.com/object-relational-mapping/
71
Logos
Use of Logos In any cover material for documentation generated at NCICB, three logos
in NCICB must be used:
Documenta-
tion • NCI. The term “Center for Bioinformatics” is inserted below the NCI logo.
• NIH
• DHHS
File copies of these logos can be obtained on the NCICB intranet:

http://ncicbintra.nci.nih.gov/ncicb_common/#logos. You must provide your
NCICB user name and password to access the intranet.
See the cover for this Technical Publications Style Guide for an example in
the appropriate use of the logos.
Use of Logos In any cover material for documentation generated for or by caBIG, the
in caBIG™ caBIG logo must be used. Unless generated by or related directly to the NCI
Documenta- or its Center for Bioinformatics, the NCI logo should not be used, but the
tion words “National Cancer Institute” should be included.
Examples of the use of these logos can be seen in the documentation and
training templates on the caBIG™ website:
https://cabig.nci.nih.gov/working_groups/Training_SLWG/Documents/index_
html
Copyright
Documentation produced by the NCICB is considered free-source and thus is never
copyrighted. The phrase “This is a U.S. Government Work” should be added at the front of the
document.
Punctuation
NOTE:
If your sentence is so complicated that no amount of
punctuation seems adequate, reorganize your thoughts and
rewrite your sentence.
72
Commas • Do not use a serial comma (before the “and”) when writing a series.
• Use a comma following an introductory phrase.
Example: From the Viewer, you can run a database search.
• Use a comma instead of a semi-colon between items in a series unless
one of the items includes a comma.
Example: Technical writers routinely generate software documentation
that can include technical guides, user’s manuals, installation guides and
release notes.
• Do not use a comma to join two independent clauses unless a
conjunction is included.
Example: Click Properties, and then click Permissions.
• Do not use a comma between the verbs of a compound predicate.
Example: The UML provides specific notations to designate these
different kinds of relations and enforces a uniform layout of the objects’
attributes and methods.
• Do not use a comma in month-year formats. Example: caCORE version
3.0 was released in March 2005.
Quotation • Avoid using quotation marks, except for when writing a direct quote.
Marks
• Example of what to avoid: Use the Camera tool to take a “snapshot” of
the graphic.
Colons • Use a colon after a complete sentence or phrase that introduces a list.
Do not use a colon to introduce art, tables, sections, or procedures.
• Never use a colon after a verb or preposition because it separates a verb
from its compliment.
° Example of correct usage: The following topics are covered in the
chapter:
° Example of incorrect usage: Navigation tools are:
Periods Use only one space after periods.
73
Semicolons • Use a semicolon between related independent clauses (complete

sentences or thoughts).
• Use a semicolon between independent clauses joined by a conjunctive

adverb, such as indeed or however.
• Use a semicolon between items in a series when one or more of the

items contains a comma.
Example: For example, they will be able to integrate and compare

information based on tumor pathology; data from RNA, DNA, and protein
expression levels (integrating genomic, expression array, and proteomic
experiments); and data collected from patients involved in clinical trials.
Bulleted Lists For top-level bullets and for sublevel bullets, use the styles indicated in the
example below. Bullets can be flush left or indented .25 inch, depending on
the location of the list. (For example, in this section, top-level bullets are
indented 0.25 inch.) Sublevel bullets (open circle bullets) are indented 0.25
inch from the primary bullets.
Example:
• XML Metadata Interchange (XMI) Version of the sample model
o cabioExampleModel.xmi
• Framework packages
o gov.nih.nci.system
o gov.nih.nci.common
o hibernate.net.sf.hibernate
• Configuration files to enable you to customize your installation to
meet your specific database, server, and other network needs
o deploy.properties
o download.properties
74
Hyphens • Hyphenate two or more words that together create a new meaning.
Example: use-case diagrams
• Hyphenate a compound modifier before a noun, whereas do not

hyphenate the same two words used as a noun.
Example: We offer leading-edge technology.
Example: We are on the leading edge.
• Hyphenate words that otherwise might be misread, such as re-creation.
If many hyphenated words appear at the right margin of a page, reading the
text can be distracting. You may want to review the hyphenated words and
their length and determine if the syntax can be changed or if some words can
be moved to the next line.
Em-Dashes Use an em-dash to show a change in thought or clarity (no space before or
and En- after).
Dashes
To configure Word to create em-dashes automatically as you type, follow
these steps:
Step Action
1 On the Tools menu, click AutoCorrect, and then click the AutoFormat
As You Type tab.
2 Select the Symbol characters ( -- ) with symbols ( — ) check box.
3 Click the AutoFormat tab.
4 Select the Symbol characters ( -- ) with symbols ( — ) check box.
When you type text followed by a space, one or two hyphens, and then one
or no space, followed by more text, Microsoft Word automatically inserts an
en dash ( – ). For example: "See pages 3 - 10" becomes "See pages 3–10."
When you type text followed by two hyphens ( -- ) followed by more text,
Word automatically inserts an em dash ( — ). Do not type any spaces on
either side of the hyphens. For example: "Many pines--ponderosa, for
example--grow here" becomes "Many pines—ponderosa, for example—grow
here." The em dashes do not appear as such until you press the space bar
after the word entered following the two dashes.
Examples of em dashes:
• Created incorrectly: Create new Proprietary Field--Enabled only for

Main Administrator
• Created and used correctly: Products—caCORE and caARRAY—are

advanced technologies.
75
• Created correctly, but en dash preferred in this situation: Create new

Proprietary Field—Enabled only for Main Administrator
• Correct: Create new Proprietary Field – Enabled only for Main

Administrator
Use an en-dash to connect elements, such as ranges of numbers, figures

and dates.
Example: See pages 4–7.
Punctuation Explain the use of punctuation when it is part of a command.

in Commands
Example: When the dialog box displays, enter “pathname” in the Path field.
The quotes are required.
Sentence Structure
Parallel Sentences should be written using parallel construction. In parallel
Construction construction, elements that are similar in purpose are also similar in
grammatical form. Although many elements should be parallel, the concept is
easily illustrated in a series or lists of items.
Incorrect:
• These parameters influence the interaction of the primer pair with the
selected target sequence and include such details as % GC, melting
temperature and how long the primers are and what the concentration of
the primers in the reaction mixture is.
Correct:
• These parameters influence the interaction of the primer pair with the
selected target sequence and include such details as % GC, melting
temperature, length of primers and the concentration of the primers in the
reaction mixture.
Text in lists should also use parallel construction.
Incorrect:
The MDA approach is as follows:
• Analyze the problem space and develop the artifacts for each
scenario.
• Use cases
• Designing the system by developing artifacts based on the use case.
Correct:
Following are descriptions of these elements:
76
• A use case, drawn as a horizontal ellipse, defines a sequence of actions

performed by the actor.
• An actor represents a person, external system, or organization that
defines a consistent set of roles when interacting with the system. Actors
are depicted as stick figures.
• An association, drawn as a solid line connecting a use case and actors to
one another, exists when an actor is involved with an interaction
described by a use case.
Spacing
Between Insert one space between sentences.
Sentences
Capitalization Capitalize the following types of words:
• Proper nouns (window, column and field names)
Example:
Unified Modeling Language
• Main words of titles and headings

• First word of items appearing in a bulleted list
General
• Do not use all upper case letters for emphasis.
• Do not capitalize the spelled-out form of an acronym, unless it is
appropriate.
• Avoid over capitalization. It is distracting to readers.
Interface
• Follow the interface for menu names, command and button names, and
dialog box and tab titles. Usually these use title caps. If the interface is
inconsistent, use title caps.
Examples:
Main Menu
Text Direction dialog box
• Follow the interface for dialog box elements. Usually these use sentence
caps. If the interface is inconsistent, use sentence caps.
Example:
External Input tab
• Capitalize the names of functional elements that do not have a name in
the interface such as toolbars and toolbar buttons (e.g., Viewer toolbar
77
and Search button). Do not capitalize generic interface elements, such

as toolbar, pane, menu, and scrollbar.
Example:
Viewer Toolbar
Save to File button
Titles and Headings
• Capitalize all nouns, verbs (including is and other forms of be),
adjectives (including this and that), adverbs (including than and when),
and pronouns (including its).
• Capitalize first and last words regardless of their parts of speech.
• Capitalize prepositions that are part of a verb phrase (Logging On to the
Network).
• Do not capitalize articles unless an article is the first word in the title.
• Do not capitalize coordinate conjunctions (and, but, for, nor, or).
• Do not capitalize prepositions of four or fewer letters.
• Do not capitalize “to” in an infinitive (How to Log On to the Network).
• Capitalize the second word in compound words if it is a noun or proper
adjective or the words have equal weight (Cross-Reference, Read/Write
Access). Do not capitalize the second word if it is another part of speech
or a participle modifying the first word (How-to).
NOTE:
Generally, starting a sentence with a word that begins with lower
case should be avoided. In the case of NCICB and caBIG,
however, exceptions are granted because so many proper names
associated with NCI, such as caMOD, caLAB, caBIG, caArray,
etc. start with “ca…” representing cancer.
Active and Use the active voice to emphasize someone performing an action. When
Passive Voice writing in the active voice, the doer is addressed as “you.”
Use the passive voice to emphasize the thing being done.
78
Tense Write manual operations and descriptions in the present tense, unless the
context requires future tense.
Example of incorrect use of future tense:
Scroll bars will appear in a pane when its contents exceed the viewing area.
Example of correct use of present tense:
Scroll bars appear in a pane when its contents exceed the viewing area.
Example of correct use of future tense.
Warning! Deleting an object will permanently delete it from the database.
Articles Articles such as “and, ”a” and “the” modify nouns indicating general or
restricted meaning. Because articles provide important meaning, do not
eliminate them in an effort to be brief.
Example of general meaning: Installing software
Example of specific meaning: Installing the software
Numbers • Use numerical numbers for any number expressing time, date,
measurements, or approximations.
• Generally, spell out numbers below 10. For numbers 10 and above, use
numerical figures. If a sentence contains both, use numerical figures.
• Place a hyphen between a number and unit of measure when they

modify a noun. Example: 12-dimensional vector
• Treat decimal representations consistently, especially when presenting

them in columns, rows, or groups.
• Do not begin a sentence with numerals.
• Spell out numbers that begin a sentence.
Precision in Writing
Jargon Jargon is perfectly acceptable, as long as it is acceptable and understood by

our professional audience. Remember that we are communicating between
two technologies—software and bioinformatics.
79
Abbreviations Spell out acronyms and abbreviations the first time they appear in the
and document, followed by the acronym in parentheses. For subsequent
Acronyms reference within a document, use only the acronym.
Example of first occurrence: Shawn is visiting the National Institutes of

Health (NIH).
Example of second occurrence: Shawn returned from the NIH.
Registered As often as possible, use generic terms to refer to products. If you must refer
Trademarks to a product with a copyright © or trademark ® or ™, be sure the front matter
of the document contains the appropriate information. It is not necessary to
use the copyright or trademark symbol within the document after its first
occurrence, unless it has been mandated.
Text Conventions
Fonts The following table describes the conventions used in manuals published by
the NCICB Technical Writing Team:
Convention Description Example

Bold & Capitalized Indicates a Menu command Admin > Refresh
Command
Indicates Sequential Menu
Capitalized command > commands
Capitalized command
TEXT IN SMALL CAPS Keyboard key that you press Press ENTER
TEXT IN SMALL CAPS + TEXT IN Keyboard keys that you press Press SHIFT + CTRL and then
SMALL CAPS simultaneously release both.
TEXT IN SMALL CAPS Keyboard keys that you press in Press ENTER, then TAB to
sequence commit the change
followed by
TEXT IN SMALL CAPS
Special typestyle Used for filenames, directory URL_definition ::=

names, commands, file listings, url_string
and anything that would appear
in a Java program, such as
methods, variables, and
classes.
Icon A toolbar button that you click Click the Zoom In button (
) to enlarge the image
Boldface type Options that you select in dialog In the Patterns Search dialog box,
boxes or drop-down menus. click the Add button.
Buttons or icons that you click.
80
Convention Description Example

Italics Used to reference other caCORE Software
documents, sections, figures, Development Kit 1.0
and tables. Programmer’s Guide
Italic boldface type, Text that you type In the New Subset text box,
monospace type enter Proprietary
Proteins.
Note: Highlights a concept of Note: This concept is used
particular interest throughout the installation
manual.
Warning! Highlights information of which Warning! Deleting an object
you should be particularly will permanently delete it
aware. from the database.
Word Usage
Word Choice The table of contents gives readers an outline of the material, an indications
for Titles of what the author considers major and minor topics, and a map leading to
the information they need.
See also Heading Styles on page 22.
Word Choice Use

Chapter titles These should make sense to a beginner. Because they should give a
good indication of the chapter contents, avoid using generic chapter titles,
such as “Introduction” or “Tutorial”.
Heading levels First level headings should target beginners; e.g. “Connecting the Cables”.
Lower-level headings can begin focusing on more specific descriptions of
your subject “Connecting Directly to the FlashCard through the Slow
Charger”.
Word choice for Put troublesome issues in headings so they are quick to spot.
headings
Examples:
• Freeing Up Memory
• If Your Document Won’t Print
Use verbs, not nouns for heading. Verbs suggest user actions:
Examples:
• Use “Deleting Words and Phrases”, not “The Delete Function”.
• Use “Searching the Database”, not “The Search Function”.
81
Word Choice Use

Heading Length Keep headings short enough to scan easily. Avoid using headings that
take up an entire line.
Examples:
Incorrect: The Distinction Between Logical and Physical Devices Under
this Operating System
Correct: Using Logical and Physical Devices
Screen The following table contain a list of terms that pertain to screen elements and
Element Word software and hardware and the way they should be used in manuals:
Choice
Word Choice Use

Tab vs. Page Use page to refer to one of a collection of Web documents that the user is
on or should refer to.
Example: On the login page…
Use tab to refer to a tab in a dialogue box. Do not use tab as a verb.
Example: Click on the Preferences tab.
Program vs. Application If possible, refer to a product by its descriptor rather than program or
application.
If not possible, use the following guidelines:
Use program since it is considered to be friendlier than application to the
end-user. Usually it refers to an executable.
Use application when referring to software that includes both executables
and other components, such as databases. Use also when the user is an
administrator, developer, or technical support specialist.
Web site vs. Website Use Web site as two words and capitalize Web.
Box vs. List vs. Field Use text box instead of field to refer to any box to which you can enter
text within a dialog box. For dialog boxes that display a list, use list
instead of box for clarity.
Example: Type a number in the Number text box. Select a format from the
Format list.
Indexes vs. indices In most cases, use indexes as the plural form of index; reserve indices for
references to math
Check box Use check box to refer to boxes within dialog boxes in which an “x” or a
check mark is placed.
Use select or clear to refer to changing the state of the check box. Do not
use check/uncheck, turn on/off, mark/unmark etc)
Combo box A combo box is the technical term for the dialog box that is a text box with
an attached list box accessed with a downward arrow. Do not use this
term in end-user documentation. Use the name of the box and the word
“drop-down menu” instead.
82
Word Choice Use

Dialog box Use dialog box, not dialog.
List box
Drop-down menu A text box with an attached list box accessed with a downward arrow. Use
this term instead of combo box, used in some settings. Use the name of
the box and the word “drop-down menu” instead.
Toolbar
Command vs. Menu Use menu option not command, choice or item.
Option
Example: Most menu options duplicate functions activated by toolbar
buttons.
Example of menu option: Click File > Open.
Icon vs. Button Use button to refer to the name of a command button on a toolbar or an
action button in a dialog box.
Use the {name of the button} button ({button image}).
Example: To return to the initial mode, press the Fit to Window button
( ).
Use icon to refer to art associated with a button or screen element; icon is
also used to refer to such elements on a tab or a screen, unassociated
with a button.
Example: Click the Remove icon ( ) corresponding to the model you

want to remove.
Back end Avoid using the jargon back end in end user documentation. Use terms
like server, operating system, and network instead.
Computer vs. Machine Use computer, not machine, PC, or box. Also use server where
appropriate.
Word Choices
for Giving
Software
The following table contain a list of terms that pertain to screen elements and
Instructions
software and hardware and the way they should be used in manuals:
and
Conveying
Results
Word Choice Use

Click vs. Press Use Click to refer to selecting a command or button of the screen. Example:
Click the Run button and then click OK.
Use Press to refer to pressing a keyboard key and holding it down.
Example: Press CTRL + SHIFT to select the object.
83
Word Choice Use

Select vs. Highlight Use Select to refer to choosing a screen element that will be subject to a
user’s action such as text, cells, panes, menus etc.
Example: Select the text in the cell. Click + drag the mouse across the text
to select it.
Use Highlight to specifically refer to a highlighter in a program such as
Word that is used to emphasize a selection.
Example: Highlight to select the range of cells to copy.
Log in vs. Login; Log Use log on/in and log off/out as verbs to refer to connecting to and
out vs. Logout disconnecting from a network or application.
Use logon, login, etc as adjectives.
Example: Log on to the network and type your login name and password.
Back up vs. backup Use back up as a verb.
Use backup as an adjective.
Example: You can create individual backup files or back up the entire
server.
Type vs. Enter Use type to refer to information the user types on the screen from a
keyboard. An exception is that users can enter a filename.
Example: Type your password and then enter the filename.
Available vs. Enabled, Use available and unavailable to refer to commands and options. Do not
Unavailable vs. use grayed out, disabled, enabled, or unenabled.
Disabled vs. Grayed
Example: The File menu is available when the user’s permission is changed
out
but the Edit menu remains unavailable.
Appears vs. Displays Use appears as an intransitive verb; use displays as a transitive verb. If
necessary, use the passive is displayed.
Example: If you type an incorrect password, a message appears. A
message displays if you type an incorrect password.
Cancel, Clear vs. Use cancel or clear but do not use deselect, especially in the case of check
Deselect boxes.
General Word The following table contain a list of general terms and the way that they
Choice should be used in manuals.
Word choice Use

Please Avoid the use of “Please” in writing instructions or comments. “Please…”
can be interpreted that a required action is optional. Even if it is omitted,
“please” is implied in instructions you write.
Afterward Use “afterward” rather than “afterwards”.
84
Word choice Use

That vs. Which Use that to set off a restrictive clause—a clause absolutely necessary to the
sentence—and which to set off a non-restrictive clause—a clause that adds
descriptive matter but is not necessary to the sentence. Generally which is
set off by commas.
Example:
Ambiguous: The build which is not ready for release was released anyway.
Can mean one of the following:
The build, which is not ready for release, was released anyway.
OR
The build that was not ready for release was released anyway.
Can vs. May Use can to describe actions or tasks the user or program is able to do.
Example: You can use either the menu command or the short-cut menu.
Use may to express possibility or when an action’s result is unknown or

variable, not to imply the user has permission.
Example: If the table extends into the margin, you may need to resize the
table.
Client vs. Customer Use client to refer to a computer or a client object or application.
Use customer to refer to a person or institution.
Example: The customer has five client workstations.

Data Use as singular or plural in meaning but usually use with a singular verb. To
emphasize that something is plural, consider using facts or numbers.
Example: Data is returned from the search. The numbers show that the
previous data was incorrect.
e.g. vs. for example, i.e. E.g. simply indicates an example; i.e. specifies or explains. In
vs. that is documentation, use “for example”, instead of e.g. Use “that is” instead of i.e.
Examples of correct usage of abbreviations:
I like citrus fruits, e.g. (for example), oranges and lemons.
I like citrus fruits, i.e. (that is), the juicy, edible fruits with leathery, aromatic
rinds of any of numerous tropical, usually thorny shrubs or trees of the
genus Citrus.
very, really Not recommended!
Consists of vs. Use include or contain instead of comprise because comprise is generally
Comprised misused. Also use consists of or make up as appropriate.
Example: The dialog box includes a number box and a format list. The
format list and the number box make up the dialog box.
want, wish Use want.
In order to… Use to…instead of in order to…
the application name Use The only if it is part of the official name of the proper noun.
vs. application name
Correct: …caCORE…
(e.g., caCORE vs. The
caCORE
85
Word choice Use

Display window vs. This phrase is not capitalized. It is a generic term referring to any viewer
display window window in the software.
Email vs. e-mail In documentation, use email.
we vs. you vs. “the Use you in the software documentation to refer to the user. Use you …
user” instead of We … and the third person, “The user ….”
Affect vs. Effect Use affect as a verb meaning “to influence”.
Use effect as a noun meaning “a result”. Effect as a verb means “to cause”,
but its use is often thought to sound “affected”, so do not use this form.
Tip: Affect means to “cause,” and begins with an A. Effect means to “result"
and begins with an E.
86
Slide Preparation Chapter 8
Chapter 8 Slide Preparation
Overview This material is excerpted from:

MacKay, B. (1992). Projecting a Powerful Picture. Medical Meetings.
July/August, 44-45.
According to a study by Wharton Graduate School at the University of

Pennsylvania, speakers who used visual aids were twice as successful in
achieving their goals. Their audiences’ information retention increased fivefold.
Effective • When it comes to presenting words visually, presenters should think

Slide “brevity”. Use a maximum of six words across, six lines per slide. Instead of
Format complete sentences, use only key phrases or important points. Minimize
the use of vertical slides.
• Text should be easy to read. Two commonly-used typefaces are Palatine
bold or Helvetica bold.
° For title (headline) type, use 24 point or 36 point in upper- and lower-
case letters (solid upper-case is difficult to read).
° Text looks good in 18 or 24 point type.
° Graphs and tables read well in 18 point type with horizontal and vertical
elements.
° Generally, it’s a good idea to use a horizontal format with 15% margin
on all sides. That way cropping problems that could occur when slides
are projected, or printed can be avoided.
• Some effective color combinations to consider are purple and golden
yellow; royal blue, aqua and orange; and red or maroon and gray. One
color combination to avoid is blue, green and red, because people who are
colorblind have difficulty telling these colors apart. Create enough contrast
between colored text and its background that the text is easily readable.
• If text makes several important points, you should highlight each point with
a bullet. To break up the text visually and call attention to each point, use
one color for the bullet and another for the text.
• One technique to help retain interest in text slides is sequential revelation—
you can add to the points you are making one at a time. You also can
highlight the point to which you is speaking by using a brighter color for the
newest addition and a softer color for points already addressed. The
sequential revelation technique also works well with graphs and charts. For
example, a speaker can extend case or test-result graphs progressively to
compare past performance with future projections, one step at a time.
° You can also use animation to have the points enter the screen one at a
time, but over-used animation in a slide presentation can be distracting.
Use sparingly.
• Some of the best models of charts and graphs that communicate
information powerfully can be found in newspapers (USA Today) and
87
magazines (Time and Newsweek).

• Adding clip art to slides can increase audience attention—as long as it is
not overdone. A good rule of thumb is to add images to every third or fourth
slide.
NOTE:
caBIG training slides should be prepared using templates prepared by the
caBIG Documentation and Training Workspace. For more information, see
https://cabig.nci.nih.gov/training.
88
References for Technical Writers Chapter 9
Chapter 9 References for Technical Writers
Resources • The Chicago manual of style, the essential guide for writers, editors, and
publishers, 15th edition. The University of Chicago Press (2003).
• Microsoft manual of style for technical publications, Microsoft Press,

(2003).
• Tarutz, JA. Technical editing: The practical guide for editors and writers.
Hewlett-Packard Press (1992).
• Price, J & Korman, H. How to communicate technical information: A

handbook of software and hardware documentation. Addison Wesley
Professional (1993).
• Barker, T. Writing software documentation: A task-oriented approach.

Longman Publishing Group (1997).
• Blake, G & Bly, R. The elements of technical writing. Longman Publishing

Group (2000).
• Sun Technical Publications. Read me first! A style guide for the computer
industry (Second edition). Prentice Hall (2003).
89
90
Appendix A Making Edits in a PDF
For directions for enabling documents to be reviewed in Adobe Reader™, refer to the Pdf
section of the Tips, Tricks and Troubleshooting document in Chapter 6, Using Adobe
FrameMaker™.
NOTE:
To make edits in a pdf, you must have either Adobe Acrobat 6.0 or later,
or Adobe Reader 7.0 or later. The latter is free and can be downloaded or
upgraded from Adobe: http://www.adobe.com/acrobat/.
Performing To perform edits or insert comments in a pdf, perform the following steps:
Edits
Step Action
1 Open the attachment.
Notes:
• When you open the attachment, the Commenting toolbar will

probably open automatically. If it does not, select View > Toolbars >
Commenting.
• A Commenting Help topic may open automatically in a pane in the

right of your viewer. If it does not, select Help > How to … >
Comment and Markup. Related topic links display in the help pane.
• If the Commenting toolbar does not open automatically, and cannot

be opened from View > Toolbars > Commenting, your attached pdf
probably was not saved to enable commenting. Contact the person
who sent you the pdf to discuss this.
2 You can add comments, highlighting, or make text edits in the document.
To do so, use the tools on the Commenting toolbar, and/or the tools
available under the Comment & Markup button. Each is described as
follows:
• Click on the Note icon ( ). Click with your cursor in the

document where you want to insert the comment. Enter your
comments in the Note text box.
91
Step Action
• Click on the down arrow to the right of the Highlight Text icon,
displaying associated options:
Select the option you want to use. Drag the cursor across text you
want highlighted, underlined or crossed-out.
• Click on the down arrow to the right of the Text Edit icon.
At that point, a Text edit topic opens that tells you how to insert text,
delete text or replace text. Follow the directions to make the
appropriate text edits.
92
Step Action
• To add another file as an attachment to this pdf, click the down
arrow to the right of the Add Attachment icon.
a. Select Attach a File as a Comment. The cursor changes to a

Push Pin.
b. Click in the pdf where the file content is to be added and click.
c. In the dialog box that opens, navigate for the file to be added as
an attachment and click Select.
A descriptive icon of your choice is inserted in the pdf and serves as a
link to the attached file.
3 Return the file to the requestor in one of the following ways:
a. Save the file with your date and name and attach it in an email.
b. If you received the file in an email entitled “Please Review the
Attached Document…, with instructions for doing so, click the Send
Comments button on the Commenting toolbar. Follow the
instructions in the wizard to email your comments back to the
requestor.
4 The help engine uses the information from the topic text file to create
and display the popup or a text topic,.
NOTE:
You are able to review and comment on this PDF file using the free Adobe
Reader 7.0 (as well as Adobe Acrobat Standard and Professional)
because the person sending you this review had used Adobe Acrobat 7.0
Professional to create and send the attached PDF file. For more
information go to http://www.adobe.com/acrobat/.
93
94
Index
Index
Abbreviations, use of, 80 description, 6
Acronyms, use of, 80 included in, 6
Adobe FrameMaker. See FrameMaker Errata
Archiving documents, 8 content of, 7
Automatically update option, Word, 22 format of, 7
Book Figure. See also Image
organization, 9 Figures
template, 9 formats, 33
Breaks generating list, 20
inserting section, 28 Footers
section breaks, 28 inserting page numbers, 30
caBIG should include, 30
cover art, 4 FrameMaker
logo use, 72 tips for using, 47
templates, 13 troubleshooting in, 47
training slides, 88 FullShot
Callouts capturing images in, 34
inserting, 37 website, 34
styles, 38 Glossary
types, 36 description, 15
uses for, 36 Headers
Capitalization, 77 adding text, 29
Captions changing text include, 29
autonumbering, 40 should include, 29
conventions for, 39 Heading styles, 22
inserting, 39, 41 Headings, numbering, 22, 24
tips, 41 Headings, word choices, 81
Changing odd page to even, 29 Image
Chapter organization, 9 aligning with text, 35
Copyright policy, NCICB, 72 layout, 35
Copyright, use of, 80 resizing, 34
Cover art, 4 style for, 35
Creating troubleshooting, 34
a pdf from Word, 41 Images, capturing, 33, 34
a table of contents, 13 Index
an index, 16 editing, 18
callouts, 36 generating, 17
captions, 39 marking an entry, 17
cross-references, 31 selecting topics for, 16
footers, 30 styles, 19
headers, 29 tips for, 19
Word styles, 21 tips for creating, 16
Cross-reference updating, 19
inserting, 31 Information mapping, 10
styles, 32 Inserting
tips, 32 blank page, 29
updating, 32 captions, 41
Cross-references, uses for, 31 cross-references, 31
Document image, 34
archiving, 8 section breaks, 28
electronic, 7 table, 35
finalizing, 6 Jargon, use of, 79
version control, 7 Logos, use in documentation, 72
Documentation plan Microsoft Word. See Word
content, 3 Mil spec numbering, 22, 24
gathering requirements, 4 NCICB
purpose, 3 cover art, 4
Editorial review logo use, 72
95
NCICB Intranet Style

adding documents, 8 creating new, 21
revising documents, 8 headings, 22
Numbering modifying, 22
automatic appendix headings, 24 Style Guide, purpose, 1
automatic chapter headings, 24 Styles
automatic numbered lists, 26 copying between documents, 23
captions, 40 template, 9
heading, 22 Table
inserting page numbers, 29 aligning, 36
mil spec, 22 inserting, 35
odd page vs even page, 29 styles, 36
page, 28 tips, 36
paragraph, 22, 24 Table of Contents. See TOC
Numbers, use of, 79 Tables, generating list, 20
Odd page to even page, 29 Technical review
Online help for completed document, 5
advantages, 61 included in, 5
analyzing target audience, 64 Template, styles, 9
browse sequences, 63 Text conventions in document, 80
context sensitive overview, 65 Titles, word choices, 81
creating, 64 TOC
creating context-sensitive, 66 creating, 13
description, 61 formatting text in, 15
finalizing project, 68 generating in Word, 13
formatting and layout, 63 styles, 15
hypertext links, 63 updating, 14
implementing context-sensitive, 67 Trademark, use of, 80
index, 62 Word
software for, 64 Automatically update option, 22
table of contents, 62 auto-numbering chapters/appendixes, 24
topics, 62 auto-numbering lists, 26
what to exclude, 65 capturing images, 33
what to include, 64 copying styles between documents, 23
Paragraph numbering, 24 creating a pdf from, 41
PDF creating an index, 16
creating "Reader-enabled", 54 creating callouts in, 36
creating from Word, 41 creating captions in, 39
reviewing in a, 91 creating footers, 30
Punctuation, conventions, 72 creating headers, 29
References creating styles, 21
for technical writers, 89 creating tables, 35
formatting, 71 creating TOC, 13
Reviewing pdf document, 91 cross-references, 31
Screen shot inserting page numbers, 29
capturing, 33 page breaks, 28
capturing in Fullshot, 34 table of contents, 13
inserting in document, 34 table or figure lists, 20
Sentence Word usage
active vs. passive voice, 78 generic context, 84
parallel construction, 76 headings, 81
structure, 76 screen elements, 82
tenses in, 78 software use context, 83
Slides, preparing, 87 titles, 81
Snag-It website, 33
96

Technical Style Guide

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Technical Style Guide

Hochgeladen von

Copyright:

Verfügbare Formate

TECHNICAL PUBLICATIONS

Center for Bioinformatics

Revised July 10, 2006

This is a U.S. Government Work. i

This page is intentionally blank.

Chapter 2 Documentation Schedule/Process

Overview To produce on-time and accurate documents for software releases, a

Other organizations involved in the development life cycle such as

This chapter discusses what a documentation plan consists of and how it is

The phases of the schedule are discussed in the next section.

Technical Publications Life Cycle

Also acquire any documentation such as white papers, functional

• caBIG™—Cover templates for caBIG documentation has been designed

Goals for completing content should be established based on the order in

which the functionality is coded by development and made available in

A technical review should be coordinated with function and UI freezes (if

Give technical reviewers the following:

NOTE: Documents generated in Adobe FrameMaker™ must be reviewed in pdf

If a document has areas that need improvement based on the technical

In addition to incorporating technical comments and last minute UI changes,

Author’s Editor’s Task

Author’s Editor’s Task

When a document is ready for an edit or a proof, the document should be

with the following commands:

Immediately after the newly inserted commands, insert the following:

NCICB Intranet—Adding and Revising Documents

Chapter 3 Document Content

Book The manuals should have the following basic organization*:

Chapter Each chapter in a manual should have the following sections:

Appendix Caption = (auto numbers based on Appendix Heading 1)

Heading 3 = third level heading

Storing Files for storing documentation templates should be located in directories to

There are four basic principles of information mapping:

Chunking principle Group information into small,

This principle is used throughout this

Relevance principle • Place like things together

• Exclude unrelated items from each

Labeling principle Provide the reader with a label for each

Consistency principle Use consistent:

• Terms within each chunk of

• Terms in the chunk and the label

Integrated graphics Use tables, illustrations and diagrams as

Accessible detail Write at the level of detail that will make

Hierarchy of chunking and labeling • Group small chunks around a single

• Provide the group with a label

This page is intentionally blank.

Chapter 4 Using Microsoft Word™

An example of a Table of Contents with Levels 1 thru 3 Headings that

2 In the Update Table of Contents (shown in following figure) select the

• Describes how to perform a task

In selecting topics to index, note the following:

• Avoid using headings as index entries

Double- or triple-posted entries:

1. Text Pane, opening folders

Using See References:

Editing an Once an index is generated, it should be carefully reviewed for duplicate

Check the spelling

In each of these examples, the differences in index primary keywords will

Tip: To expedite editing an index in Word, use the following steps:

2 Review the index to make sure that are no formatting errors.

List of Tables or Figures

List Styles The styles, Table of Figures/Tables/Equations, are automatically created

4 Select the Add to template check box.