Sunteți pe pagina 1din 142

Documentation Department

Writing and Style Guide


Spillman® Public Safety Software

Spillman Technologies, Inc.


4625 West Lake Park Blvd.
Salt Lake City, Utah 84120
Telephone: 1-800-860-8026
www.spillman.com

First Publication: March 2004

Notice

Copyright © 2017, Spillman Technologies, Inc. All rights reserved. The information contained herein is proprietary to
Spillman Technologies, Inc.

Spillman Technologies, Inc., reserves the right to make improvements and changes in the product described in this
publication at any time and without notice, and may revise this publication from time to time without notice.

Spillman Technologies, Inc., provides this publication “as is” without warranty of any kind, either expressed or implied,
including but not limited to the implied warranties or conditions of merchantability or fitness for a particular purpose.
While every precaution has been taken in the preparation of this manual and its representation of the product, the
publisher and author assume no responsibility for errors, omissions, or any damages or loss of data as a result of said
errors or omissions.

Spillman, Summit, Sentryx, Involvements, Spillman Touch, Visual Involvements, and CrimeMonitor are federally
registered trademarks of Spillman Technologies, Inc. Spillman Flex, Spillman InSight, and Integrated Hub are
trademarks of Spillman Technologies, Inc. All other registered or unregistered trademarks and names are the property
of their respective owners. Rev. 02.19.17
Table of Contents
Preface 9
Basic guidelines 9
Spillman voice and tone 9
Spillman formatting 10
Spillman punctuation 11
Spillman capitalization 14
Spillman terms 14

1 Basic Rules of Technical Writing 17


Introduction 18

Be Professional 19
Use bias-free writing 19
Use active voice 20
Use present tense 20
Watch agreement in number 21
Do not use contractions 21
Use positive construction 22
Use American English 23

Be Logical 25
Use task completion order 25
Use one angle to present information 26
Direct readers from big to small 27
Stay within the heading topic 27

Be Accurate 28
Take responsibility 28
Question everything 29
Test your procedures 29
Ask for reviews 29

Documentation Writing and Style Guide iii


TOC
Do not retract statements 29
Do not imply that nonexistent things exist 30
Use accurate images 30
Describe screen attributes correctly 30
Describe lists correctly 31
Give all pronouns antecedents 31
Use conjunctions correctly 32
Make sure plurals and singulars are correct 32
Keep absolutes absolute 32
Use correct spellings 33
Correctly spell plurals 33
Use numbers correctly 34

Be Precise 37
Interpret facts 37
Correct misplaced modifiers 38
Avoid vague wording 39
Use the correct article 39
Be aware of implications 40
Be aware of connotations 41
Use prepositional phrases instead of possessives 44
Use symbols correctly 45

Be Thorough 48

Be Concise 50
Think about the needs of readers 50
Avoid big, pompous-sounding words 50
Keep your sentences and paragraphs short 54
Avoid redundancy and repetition 54
Cut unnecessary words 56

Be Consistent 59
Use terminology and formatting as markers 59
Present information in the same order 59
Use parallel structure 60
Use common abbreviations 60
Use alphabetization 63

iv Documentation Writing and Style Guide


TOC

2 Formatting 65
Introduction 66

Formatting Documentation 67

Formatting Voice 69
Use the second person 69
Use screen shots 70
Formatting screen shots 71
Formatting callouts 73
Choose the correct word 73
Use explicit if-then statements 84
Use coordinating conjunctions correctly 85
Eliminate run-on sentences 85
Use verbs correctly 86

Formatting Bulleted Lists 87

Formatting Capitalization 88

Formatting Commands, Files, and Menu Items 94


Formatting commands 94
Formatting files and file extensions 94
Formatting menu items 95

Formatting Cross-References 96
Understanding the lack of indexes 97

Formatting Field Descriptions 98

Formatting Fonts 99

Formatting Headings 101

Formatting Line and Page Breaks 103

Formatting Numbered Lists and Procedures 105

Formatting Punctuation 107


Formatting punctuation marks 107

Documentation Writing and Style Guide v


TOC
Using colons 108
Using commas 109
Using ellipses 110
Using em dashes 111
Using en dashes 111
Using exclamation points and semicolons 112
Using hyphens 112
Using parentheses 113
Using periods 113
Using quotation marks 115

Formatting Tables 116


Sizing tables 117
Formatting table paragraphs 117
Formatting tables for settings and privileges 118
Using “blank” as a value in a table 121
Using notes, tips, and cautions 121

3 Responsibilities 125
Introduction 126

Improve the Product 127

Label Documentation Correctly 128

Using Copyedit Checklists 129


Light Copyedit Checklist (Basic) 130
Medium Copyedit Checklist (Intermediate) 130
Heavy Copyedit Checklist (Advanced) 131

A Appendix A 133
Using function keys 133
Understanding computer terms 135

vi Documentation Writing and Style Guide


TOC
Understanding law enforcement terms 136
Using proofreader marks 138
Using style sheets 140

Documentation Writing and Style Guide vii


TOC

viii Documentation Writing and Style Guide


Preface
Welcome to the Documentation Department Writing and Style Guide.
This guide is written for Documentation department team members as a
comprehensive list of style and writing guidelines.
The Documentation department uses the following publications as guides:

The Associated Press Stylebook and Libel Manual
 The Chicago Manual of Style
 Editing Online Help by Jean Hollis Weber
 The Elements of Style by W. Strunk Jr. and E.B. White

Macromedia RoboHelp X5: HTML-Based Help, vols. 1 & 2
 Merriam-Webster’s Collegiate Dictionary
 The Microsoft Manual of Style for Technical Publications
 The Web Content Style Guide by Gerry McGovern, Rob Norton, and
Catherine O’Dowd
This manual is the definitive authority for the Documentation department, and
the guidelines in this manual trump any differences between it and the
publications listed above.
Any new documentation written after June 2017 must adhere to these style
rules and guidelines.
Not all style issues are covered in this manual. When additional style
questions come up, notify the Documentation manager so the information can
be added to this style guide.

Basic guidelines
The following sections simply and quickly identify Spillman Documentation
style.

Spillman voice and tone


Spillman voice is always the following:
 Professional, but friendly

Expert, but not bossy

Documentation Department Writing and Style Guide 9


Pre


Thoughtful, but not ponderous
 Concise, but thorough

Accurate, but not pedantic
Spillman tone is formal, and uses second person with understood you. Do not
waste the readers time with frivolity. Key elements of Spillman voice and
tone include the following:

Use active voice. Avoid passive voice, if possible.

Write positively. Use positive language rather than negative language.

Be respectful. Recognize that our customers are a busy, diverse group
of people.

Spillman formatting
The following table lists the formatting conventions used by the
Documentation department.

Convention Use Example

bold Area names In the Narrative area, select the Narrative record.

Button names Click the Validate button.

Field names In the Address field, enter the person’s address.

Folder names Open the AddData folder.

Icon names Click the Add icon.

Run-in headings Gender neutral terminology. Use dispatcher, not she.

bold Examples to enter Enter the first name of the person, such as George.
Courier (‘such as’ only)
font
Specific info to enter At the command line, enter lwmain.

10 Documentation Department Writing and Style Guide


Pre

Convention Use Example

Courier Examples to enter (‘for Enter the first name of the person. For example, George.
font example’ only)

File names Open the options.xml file.

Formats Enter the sever path using the following format: 


http://hostname:port/, where hostname is the name of your
server.

Location/directory Navigate to the /sds/Users directory.


paths Save your file to the following location:
/sds/World/Group/Users/

Message text A dialog box opens with the following message: Save a copy?

Parameter names Set the invlrshp application parameter to True.


Setting names Set the AllowPartialData setting to True.

Specific values 1/Yes/True, 0/No/False

Table names Open the Names screen (nmmain).

Table record names Codes are saved in the apagncy table.

Tags Copy the <TimeOut> tag. 

italics Variable Enter the date in the mm/dd/yyyy format.


information—usually Enter the time in the hh:mm:ss format.
related to number Enter the phone number in the (xxx) xxx-xxxx format.
formatting, such as
date, time, phone
number, or versions.

Emphasis Do not shut off your computer while saving.


(use sparingly)

Spillman punctuation
The following table lists the punctuation conventions used by the
Documentation department.

Documentation Department Writing and Style Guide 11


Pre

Convention Use Example

Colon Field descriptions within a 1. Complete the following fields:


step sub-list – Fst Name: Enter the first name of the person.
– Lst Name: Enter the last name of the person.
Introduce a bulleted list Complete the following tasks:
• Set up user privileges
• Configure web application settings
Introduce a large amount of The following message appears: Please search for an
displayed text existing record before adding a new record to
this table.

Introduce a list in a The IBR Agency screen contains the following tabs: Arrest, Offenses,
sentence and Incidents.

Introduce a paragraph of For all radio log entries, use the following format:
text the user enters unitcode ten-code comments

Introduce a procedure To create a Name record:


1. At the command line, enter names.

Introduce isolated text in a At the CAD command line, enter the AT command in the following
separate paragraph format:
at call#type {nature {address}}
where call# is the original call number.

Ellipsis Do not use. If commands or Button name: Click here to add a new record …
menu names contain an Use: Click the Click here to add a new record button.
ellipsis, then do not
document it. Screen name: Print …
Use: The Print screen opens.

Em Dash Long pauses in a sentence To protect records with a password, a user must be able to run the
(use sparingly) appropriate program—for example, the Law Incident program if the
user is protecting law records— and be able to access the Pswd option
from the option line in that program.

En Dash Indicate a range of values 8. Repeat steps 2–7 for each record.

Enter A as the first value and E as the second value to find all last names
that begin with a letter in the range A–E.

12 Documentation Department Writing and Style Guide


Pre

Convention Use Example

Period Descriptive/commanding
Activity
sentences in field
descriptions and tables. Displays the type of activity that occurred at the time of the incident.
Modify this field, if necessary.

2. Complete the following fields:


– Activity: Displays the type of activity that occurred at the time
of the incident. Modify this field, if necessary.

Intro to a table The following table lists buttons on the main toolbar.

Run-in headings Menu screens contain the following elements:


• Close button. Closes the screen.
• Title bar. Displays the name and version
When all sentences in a Once the shapefile is saved, the following occurs:
bulleted list are complete • The Save dialog box closes.
sentences • Code tables are mapped to ArcGIS.
• The mapping screen opens to the shapefile.
Parenthesis Enclosing Click the mapping icon ( ).
icon/button/symbol images
(use sparingly)

Enclosing pertinent or Complete the following tasks:


conditional information • Create Spillman records
• Create IBR records (only if your agency uses the IBR module)
• Transfer records to the copied database
Enclosing table names Open the Names screen (nmmain).

Documentation Department Writing and Style Guide 13


Pre

Spillman capitalization
The following items are capitalized in Spillman documentation:
 Keyboard key names. For example, “Press Ctrl+C to close the
screen.” Refer to the preface in the template for new manuals for
assistance on how to document keyboard shortcuts.

Official module names. For example, the Law Enforcement Records
module. Do not capitalize the word module.

Proper menu names. For example, the System Maintenance menu. Do
not capitalize the word menu. The exception to this rule is the Tree
Menu.

Proper names of record number types. For example, Booking
Number. Do not capitalize when referring to record numbers in
general.

Report names. For example, the Individual Arrest report. Do not
capitalize report.
 Specific record types. For example, a Law Incident record. Do not
capitalize when referring to records in general.
 Screen names. For example, the Additional Name Information screen.
Do not capitalize the word screen.
Do not capitalize command line.

Spillman terms
The following table lists the terms and word choice conventions used by
Spillman documentation.

Word/Term Attributes/Description Example/Reference

Appears When an item that was previously not visible In adminutil, in the Show settings for
appears on a screen due to an action the user field, if Agency is selected from the
performed. The term can also be used to describe drop-down list, then a field containing a list of
items that appear and disappear on their own. agencies appears.

Click Action used to press the left mouse button once. Click the Accept button.
Do not use click on. Buttons, icons, options, or
tabs are clicked.

Dialog box Interactive, with more than one option to select. Print dialog box
Dependent on user actions to open or continue
tasks. Typically, tasks in the dialog box must be
completed and the dialog box closed before the
user can continue.

14 Documentation Department Writing and Style Guide


Pre

Word/Term Attributes/Description Example/Reference

Displayed If information such as search results, a message, 3. Click List.


a field, or a record is displayed. Information is The search results are displayed in the list
typically displayed after the user performs an screen.
action with the software.
As a transitive verb, display requires an object.
Therefore, use the construction is displayed.

Enter Text the user enters with the keyboard, or types. In the Last field, enter the last name of the
In general, do not use the word type as in type the person.
information, because it can be used as a noun
(for example, search types).
Do not use enter in.

From The point at which an action starts. Using this From the screen toolbar, click the Invl button.
construction helps orient the user to the correct
part of a screen when following instructions.

In When something is enclosed or surrounded by On the Names screen, the Name record
something else. When fields display information, number is displayed in the Number field.
it is enclosed in the field. Therefore, in is the
correct term to use.

Log on/Log in The act of accessing the software with a Log on to the Application Server.
username and password. Do not use confuse
with the noun term of logon/login. Generally, log
on is the preferred term.

Message box Contains a message from the software, with only Save Succeeded message box
one user option to dismiss the message (usually
OK). Sometimes, there is no option.

Opens When items open separately from the current 1. At the command line, enter names.
screen, such as windows, dialog boxes, The Name screen opens.
browsers, or other screens. Do not use appears.

Press Action used to press a keyboard key, such as a Press Ctrl+P to open the Print dialog box.
keyboard shortcut. Buttons are not pressed.

Rest Action used to pause the mouse pointer on an Rest the mouse pointer on an icon to display a
item in the screen. Do not use hover. ToolTip.
Also, do not confuse cursor with mouse pointer.
The cursor is the blinking line that indicates
where text appears when the user types. The
mouse pointer is the symbol used to indicate the
part of the screen the mouse is pointing to.

Screen Interactive, with fields, often many, to complete Names screen


and options to select. Screens are typically
bigger than dialog boxes or windows.

Select Action used to select menu options or check To open the Names screen, from the Tree
boxes. Menu, select Hub Menu > Names Table.

Documentation Department Writing and Style Guide 15


Pre

Word/Term Attributes/Description Example/Reference

Set up Action used to configure the software, such as To use the module, set up the following
setting up the application parameters. Do not settings:
confuse with the noun/adjective term setup.

Window Interactive, but with fewer options to select than Undispatched Calls window
a screen.
Can be used independently of other screens.
Can be minimized to complete other tasks.

16 Documentation Department Writing and Style Guide


Chapter 1

Basic Rules of Technical


Writing

Jump to topic:
Introduction 18
Be Professional 19
Be Logical 25
Be Accurate 28
Be Precise 37
Be Thorough 48
Be Concise 50
Be Consistent 59
Basic Rules of Technical Writing
1 Introduction

Introduction
This chapter explains some basics of good technical writing, with an emphasis
on good Spillman technical writing. It includes the following:

“Be Professional” on page 19

“Be Logical” on page 25

“Be Accurate” on page 28

“Be Precise” on page 37

“Be Thorough” on page 48
 “Be Concise” on page 50

“Be Consistent” on page 59

18 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Professional 1

Be Professional
Technical writing must be professional. Documentation that looks and sounds
professional increases the credibility of Spillman.
Use the following guidelines to write in a professional tone:
 “Use bias-free writing” on page 19
 “Use active voice” on page 20
 “Use present tense” on page 20
 “Watch agreement in number” on page 21

“Do not use contractions” on page 21

Use bias-free writing


Current customers, potential customers, and Spillman employees comprise
people of various ages from all racial, cultural, and religious backgrounds
who serve populations of various ages from all racial, cultural, and religious
backgrounds. It is very unprofessional to write anything that can be construed
as biased against or stereotypical of any group of people, including gender,
race, sexual orientation, age, culture, or religion.
Use the following guidelines to keep your writing bias-free:
 Use gender-neutral terminology. For example, use police officer, not
policeman; dispatcher, not she.
 Use up-to-date, politically correct terminology. For example, use
Asian, not Oriental; sexual orientation, not sexual preference.
 Use all inclusive lists. For example, if a code table lists religions,
include as many religions as possible.

Use extreme caution when associating character traits and actions
to specific groups of people. Avoid doing so if possible. Even
associating positive character traits with a specific group can be seen as
a subtle way to imply that another group is lacking that positive
character trait.
 Use examples of all types of people in all roles. Show people of all
races and ages as officers, personnel, inmates, and citizens. Use names
that can come from many cultures and backgrounds. Do not use famous
real people or characters (for example, Harrison Ford or Han Solo) or
the real names of your friends, family, and associates.

Documentation Department Writing and Style Guide 19


Basic Rules of Technical Writing
1 Be Professional


Use plural subjects and verbs. The word they is a plural,
gender-neutral pronoun that can refer to any group of people.
Therefore, use plural subjects and they as often as possible.

Use the instead of his or her. If the article is unnecessary, then remove
it.

Use the noun again instead of a pronoun. For example, consider the
following sentences:
– To add money to an inmate’s account, in the Deposit field, enter the
amount of money he provided.
– To add money to an inmate’s account, in the Deposit field, enter the
amount of money the inmate provided.
Notice that the pronoun he makes an inappropriate assumption that the
inmate is male. Many inmates are female. Using the noun again
eliminates the assumption.
 Use the second person. If it is necessary to differentiate between an
action that the software or the reader performs, then use the imperative
second-person as the most direct and unbiased way.

Use active voice


Active voice is more dynamic and easier to read than passive voice. Active
voice also forces tighter writing. Passive voice conceals who or what is doing
the action, which can confuse readers. However, passive voice is acceptable
for describing reactions when it is not important to point out that the software
did the action. For example, writing The search results are displayed is better
than The software displays the search results.

Use present tense


Present tense emphasizes the idea that the documentation is to be read while
the task is being performed, and that the documentation is current and
valuable in the moment. However, it is acceptable to use other tenses if the
time element is critical to the meaning of the documentation. Make sure not to
switch tenses in the middle of a sentence or thought.

20 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Professional 1

Watch agreement in number


Use the following guidelines to make sure your documentation agrees in
number:
 Use plural subjects and the pronoun they as often as possible.
Because the English language lacks a singular, gender-neutral,
third-person pronoun, making sure singular subjects are matched with
singular pronouns can be difficult. If it is inaccurate to use a plural
subject, then using they as a singular, gender-neutral pronoun is
acceptable.
 Pay particular attention to sentences with the words and and or in
them. The word and often signals a plural subject, and the word or
often signals a singular subject. However, there are exceptions for both
words.
 Pay attention to subjects and verbs that are separated by clauses or
prepositional phrases. Consider the following example:
The classes and experience at our beautiful campus prepares our
students for the real world.
If the writer had taken out at our beautiful campus, it might have been
more clear to them that because classes and experience are both the
subject of the sentence, prepare is the correct verb.
The following table lists some common number agreement mistakes.

Incorrect Correct

The user must save the record, and after Users must save the record, and after they
they have done so... have done so...

If either the No Match or Partial Match If either the No Match or Partial Match
columns display a high number, then... column displays a high number, then...

To find the Name records for all persons To find the Name records for all persons
whose last names begin with the letters A, whose last names begin with the letter A, B,
B, or C... or C...

Press the Up Arrow or Down Arrow keys Press the Up Arrow or Down Arrow key
to... to...

Do not use contractions


Contractions are more casual than professional, and apostrophes clutter a
clean page. Write out the phrase instead. One method of checking for the use
of contractions is the Find command in FrameMaker.

Documentation Department Writing and Style Guide 21


Basic Rules of Technical Writing
1 Be Professional

To find all apostrophes in a book or document:


1. In FrameMaker, from the menu bar, select Edit > Find/Change.
The Find/Change box opens.
2. From the Field drop-down list, if necessary, select Text:.
3. In the Find field, enter an apostrophe (‘).
4. Click Find.
FrameMaker finds the next instance of an apostrophe.
5. For each apostrophe found, do one of the following:
– Change the contraction to the appropriate phrase.
– Make sure the apostrophe is used to indicate possession, and that
the possessive is correct. Make sure the possessive makes sense
and does not clutter the sentence or meaning. Otherwise, reword.
6. Repeat step 4–5 until all instances have been found, reviewed, and, if
necessary, corrected.

Use positive construction


In most cases, positive construction is better than negative construction.
Telling readers what they can do is better than telling them what they cannot
do. Occasionally, a negative construction is acceptable for emphasis. The
following table shows examples of how to use positive and negative
construction correctly.

Negative Construction Positive Construction

Do not change the communication port Change the communication port settings in
settings in Spillman Mobile unless the Spillman Mobile only if the settings used by
settings used by the GPS device are known. the GPS device are known.

Not only can this be done, but so can this. This can be done, and this can be done.

Do not turn off your computer while the None.


information is saved. In this case, the negative construction is the
most direct way to convey the importance of
the instruction.

22 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Professional 1

Use American English


Although Motorola Solutions, Inc is an international company, Spillman
Technologies, Inc. has been an American-based company with American
customers. Unless otherwise instructed, the Documentation department uses
American English and American spellings.
In addition, use the Imperial system standard measurements (feet, miles,
pounds, ounces, and so on) rather than metric (meters, kilometers, kilograms,
grams, and so on). Sometimes, metric measurements are appropriate, such as
when giving an example of measurements of drugs, which can be in grams.
When in doubt, talk to the Documentation department manager.
The following list, from The Web Content Style Guide by Gerry McGovern,
Rob Norton, and Catherine O’Dowd, presents some differences between
American and British English:
 Date style. American English generally places the month before the
day (August 3, 2001, or 8/3/01), while British English places the day
before the month (3 August 2001, or 3/8/01).
 Punctuation. American English uses the serial comma (the comma
before the and or the or in a series of three or more items), while
British English generally drops the comma.
American English always places the closing quotation mark after the
period or comma (but not after the dash, colon, or semicolon), while
British English generally places the closing quotation mark after the
period or comma only when the quoted matter is a grammatically
complete sentence.
 Quotation marks. American English generally uses double quotes
(“b”), while British English generally uses single quotes (‘b’)
 Spelling. American English and British English have many spelling
differences. The following table highlights the main differences, but it
is not exhaustive, and there are exceptions to these guidelines. When in
doubt, consult a dictionary. FrameMaker accepts both British and
American spellings of many words, so do not rely on the spelling
checker in FrameMaker.

American British Example

ize ise capitalize, capitalise

am amme program, programme

ay ey gray, grey

ck que check, cheque

e ae archeology, archaeology

Documentation Department Writing and Style Guide 23


Basic Rules of Technical Writing
1 Be Professional

American British Example

e oe fetal, foetal

er re fiber, fibre

eu oeu maneuver, manoeuver

f ph sulfur, sulphur

ing eing aging, ageing

l ll traveled, travelled

ment ement judgment, judgement

og ogue dialog, dialogue

ol oul mold, mould

or our color, colour

ow ough plow, plough

sk sc skeptical, sceptical


Word Choice. The following table lists a few examples of how
American English word choice is different from British English word
choice.

American British

first, second (in enumerations) firstly, secondly

forward forwards

toward towards

last name surname

fall autumn

24 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Logical 1

Be Logical
Technical writing must be logical. Readers of technical writing are normally
trying to accomplish a task. Therefore, all manuals must be task-oriented and
logical so users can quickly find information.
Do not describe the product. Instead, present readers with the steps required to
complete specific tasks. When describing the fields on a screen, explain the
information that should be entered in the fields. Use cross-references as
needed to direct readers to connected information.
Make sure all tasks are discussed individually and simply. All task
descriptions must follow a logical order.
Use the following guidelines to organize your documentation logically:
 “Use task completion order” on page 25
 “Use one angle to present information” on page 26
 “Direct readers from big to small” on page 27
 “Stay within the heading topic” on page 27

Use task completion order


Tasks should be presented in the order that readers must complete them. For
example, if readers must search for records before adding records, then
present the task of searching before the task of adding.
If there is not a specific order the tasks must be completed in, then present the
information in the order it is presented in the software, left-to-right,
top-to-bottom.

Documentation Department Writing and Style Guide 25


Basic Rules of Technical Writing
1 Be Logical

Use one angle to present information


Tasks should be presented from one angle. Having too many approaches can
cause readers to assume that the manual is proceeding to a new topic. It
confuses the reader. Present each task from only one perspective. For
example, if a procedure and a command syntax need to be explained, then
incorporate the syntax into the early steps of the procedure.

Incorrect Correct

To add a call type for an active call, use the To add a call type for an active call, use the
AT (Add Type) command. The usage for AT (Add Type) command as follows:
this command is as follows: 1. In CAD, enter the at command in the
following format at the command line:
at {call# {type}{nature
{address}}} at {call# {type}{nature
Suppose you want to add an EMS call type {address}}}
to an active call (7f) that currently only has
the type fire. To do this, enter at 7e. where call is the original call number
If you want a different nature or address for and type is the call type to add. A new
the EMS type call, you can enter the new nature and address for the new call type
nature or address after the AT command. can be specified, or the nature and
Otherwise, the software uses the nature and address can be omitted to use the
address of the original call. To add a call nature and address from the original
type: call. For example, enter at 7e to
1. In CAD, enter the AT command add the EMS call type for call 7, using
followed by the call number of the the same nature and address as the
original call and the call type that you original call.
want to add at the command line. For
example, enter at 7e.

If there is more than one way to complete a task, then clearly define the
different methods. Analyze your writing and others’ writing to be sure that all
tasks are discussed individually and, therefore, more simply.

Incorrect Correct

In CAD, enter the MT command followed At the command line in CAD, the
by the call number and type at the command highlighted call can be modified or a
line. For example, enter mt 6e. different call to modify can be specified.
Note: If you do not specify a call number, • To modify the highlighted call, enter mt.
the software opens the call that is • To modify a different call, enter mt
highlighted on the CAD Status screen. followed by the call number and type.
For example, to modify call 6e, enter mt
6e.

26 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Logical 1

Direct readers from big to small


Documentation must start with generals and then add specifics. First, tell
readers what task is being described, where the task is performed, and then
what actions are required to complete the tasks. For example, To open the
Booking Checklist, from the Inmate List screen, select the desired inmate, and
then click the Booking Checklist button.
When detailing what a screen is used for, begin by describing the whole
screen, then the sections or tabs on the screen, and finally the buttons or fields.

Stay within the heading topic


Each heading should give the reader a precise idea of what the section
explains. Do not include information that is not mentioned in the heading.
Readers must be able to see the organization in a glance, and trust that the
headings are accurate maps of the documentation.
Subheadings should also be subtopics of the main heading. If the topic
discussed in the subheading is not directly related to the main heading, then
find a different place to put the subheading’s information.
Introduction and overview sections are not exceptions to this guideline.
Introductions and overviews provide a brief explanation of what the chapter
or section explains. Do not insert valuable information that deserves its own
heading in an introduction or overview.

Documentation Department Writing and Style Guide 27


Basic Rules of Technical Writing
1 Be Accurate

Be Accurate
Information in the documentation must be accurate. If the documentation's
description of the software does not match the features of the software, then
customers can demand that Spillman change the software to match the
documentation. Missing or inaccurate documentation can also contribute to
data problems for a customer, which can lead to other problems, including
officer safety concerns or legal action.
Use the following guidelines to help ensure accuracy in your documentation:

“Take responsibility” on page 28

“Question everything” on page 29

“Test your procedures” on page 29
 “Ask for reviews” on page 29
 “Do not retract statements” on page 29

“Do not imply that nonexistent things exist” on page 30
 “Use accurate images” on page 30
 “Describe lists correctly” on page 31

“Give all pronouns antecedents” on page 31
 “Use conjunctions correctly” on page 32
 “Make sure plurals and singulars are correct” on page 32

“Keep absolutes absolute” on page 32
 “Use correct spellings” on page 33
 “Use numbers correctly” on page 34

Take responsibility
Each piece of assigned documentation is your responsibility. Do not assume
the previous writers who worked on the manual caught all inconsistencies or
inaccuracies. Writers are people too, and people make mistakes. Make sure
the document has accurate information and formatting, whether the document
is new or being revised.

28 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Accurate 1

Question everything
Do not assume anything. Ask your development teams for clarification of
features and designs that are not clearly explained in design documents. If the
software does not behave in the expected way, then ask about settings or other
issues that could be present in either your computer or the development
servers.

Test your procedures


Follow the instructions yourself, or ask a member of the Quality Assurance
(QA) department or another writer to test them. Follow the procedure
completely, even if the outcome or behavior of the software is familiar or
anticipated. Often the software does not work in the expected way.

Ask for reviews


Reviews are a vital part of accurate documentation. Each document, whether
new or revised, must be reviewed by a subject matter expert (SME). The SME
can be a Developer, Quality Assurance Analyst, or another member of the
project team. Technical reviews might need to be completed by more than one
SME to get the full picture. For final technical reviews, ask the Project Line
Manager (PLM) or Business Analyst (BA) for a review. They have final say
on what the product requirements are.

Do not retract statements


Never tell readers to do something and then retract the statement. Each
sentence should be accurate on its own. If conditions apply, then include the
conditions in the statement first. The following table shows an example of
individual sentences that are not accurate on their own, and a corrected
version.

Incorrect Correct

Use the Secure Sockets Layer (SSL) If your agency has a Virtual Private
command to start the Apache Web server. Network or a Secure Private Network that
Start Apache with SSL encryption if you do provides encryption protection, then the
not have encryption protections through Apache web server can be started without
some other means (such as a Virtual Private using the Secure Socket Layer (SSL)
Network or a Secure Private Network). Start command. Otherwise, use the SSL
Apache without SSL encryption if you do command to start Apache.
have encryption protection through some
other means.

Documentation Department Writing and Style Guide 29


Basic Rules of Technical Writing
1 Be Accurate

Do not imply that nonexistent things exist


Do not imply that readers have options they might not have, or that the
software will do something when it might not. If the available options depend
on software versions or settings, then state so first. The following table shows
an example of implying something that is nonexistent.

Incorrect Correct

You have the following options: Your next action depends on your
• If you have the necessary privileges, privileges:
do... • If privileges have been granted, then
• If you do not have the necessary do...
privileges, do... • If privileges have not been granted, then
do...

In addition, do not imply that existent things do not exist. For example, it is
more accurate to write if a matching record is not found rather than if a
matching record does not exist. A matching record might exist, but the user
might have used incorrect search criteria.

Use accurate images


Images are powerful tools to show readers the software. However, images
work only if they are accurate. Make sure images support the point being
made. Also make sure images accurately show the software, such as when
emphasizing a behavior based on a setting.
For more information on images, see “Use screen shots” on page 70.

Describe screen attributes correctly


It is impossible to know how different monitors will display changes in
appearance in the software. Therefore, avoid describing specific screen
attributes, such as blinking or changing color. Instead, use more generic
descriptions, such as the wanted alert appears in the upper-right corner. If a
change in screen attributes must be directly referenced, then write something
similar to the following: the timeout alert changes appearance (for example,
blinks or changes color, or both) on your screen.

30 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Accurate 1

Describe lists correctly


Some lists in your documentation will be complete lists, while others will be
only representative. Make sure the words introducing your lists accurately tell
readers which type of list they are reading.
Lists introduced with the words include, including, or such as are understood
to be partial lists. If a list is complete, then introduce it with a term that
connotes completeness, such as contains or comprises.
Using the phrase and so on is an acceptable way to indicate a list is partial.
Use and so on only with lists that have at least three items. Do not use and so
on with such as or including because both phrases imply that the list is partial.
Do not use etc. or etcetera.

Give all pronouns antecedents


Pronouns are words that replace nouns, and help your documentation feel less
stiff and repetitive. However, pronouns without clear antecedents can make
your documentation inaccurate and confusing to readers. Make sure it is clear
what each pronoun is referring to. It is better to repeat a noun again than to use
a vague pronoun. The antecedent of a pronoun should be a single word or
phrase, not a general idea. Do not use headings as antecedents for pronouns.
The words this, that, these, and those are all trouble pronouns that often have
vague antecedents when used alone. Most of the time, it is better to use these
words are demonstrative adjectives, rather than as pronouns.
The following table shows examples of pronouns with missing or unclear
antecedents and better versions.

Incorrect Correct

If the street crosses a zone or city boundary, If the street crosses a zone or city boundary,
then break it into segments. then break the street into segments.

The file is added to the folder, and it is The file is added to the folder, and the folder
saved on the server. is saved on the server.

Exporting the files to a different server Exporting the files to a different server
creates a backup of the data. This makes creates a backup of the data. Exporting the
sure it is protected even if the original server files makes sure the data is protected even if
fails. the original server fails.

Single Table Join Single Table Join


This is the simplest of the different joins The Single table join is the simplest of the
that can be performed. different joins that can be performed.

This table lists the settings for the module. The following table lists the settings for the
module.

Documentation Department Writing and Style Guide 31


Basic Rules of Technical Writing
1 Be Accurate

Use conjunctions correctly


The words and and or are both used to connect words, phrases, and ideas to
each other. More often than might be expected, developers and other writers
can use and when they mean or, or vice versa.
Each word also has several connotations. For example, the word or can mean
if this one is picked, then never that one, but sometimes or can mean this one
and that one, but not at the same time. The word and has similar connotative
nuances. Make sure the context makes the connotation of the words clear.
If the concept this one, that one, or both needs to be presented, then use the
following format:
A or B, or both
where A and B are the choices. This format is better than using the
construction and/or.

Make sure plurals and singulars are correct


Sometimes, it is easy for writers to use plurals even when the singular case is
correct. This tendency exists in developers as well as technical writers.
Question your own use of plurals and singulars, as well as their use in design
documents. Misuse of plurals and singulars can cause confusion for readers.
For example, if the software saves a file in a specific folder, but the
documentation uses folders, then readers might be confused because they
could be looking for an extra folder that does not exist.

Keep absolutes absolute


Certain words have an absoluteness to their meanings. Some of these words
are obvious. It is impossible for a person to be a little pregnant or very
unconscious. Other absolute words are less obvious. For example, it is
impossible for something to be most current, or completely lost. Our culture
accepts these phrases as idioms, but in formal, technical writing, these phrases
are not accurate. Think about what these phrases imply: that there are degrees
of up-to-date-ness, and that something can be incompletely lost. Make sure
absolutes are used accurately.

32 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Accurate 1

Use correct spellings


Incorrectly spelled words make reading documentation more difficult, and
can create inaccuracies in the text. Use the spelling checker, but also check for
misspellings of words that it cannot catch. For example, typing form when
from is correct.
The following is a list of frequently misspelled words used by the
Documentation department. Note the correct spellings.
 addenda  lowercase (one word)
 agencies (plural)  men’s

agencies’ (plural possessive) 
online (not on-line)
 agency (singular)  onto (except in log on to)
 agency’s (singular possessive)  ours
 appendix, appendices  scroll bar (two words)
 children’s  theirs
 en route  toolbar, toolbars (one word, not
tool bar)
 file name  ToolTip (note the abnormal
capitalization)
 fingerprint  uppercase (one word)
 indexes (use indices only for  username (one word)
mathematical expressions)
 its (not it’s, which is the  women’s
contraction for “it is”)
 Linux  yours

Correctly spell plurals


Some words have special rules to follow when making plurals. Following
these rules keeps the documentation accurate and consistent.
For more information, refer to the Microsoft Manual of Style.

Documentation Department Writing and Style Guide 33


Basic Rules of Technical Writing
1 Be Accurate

Plurals of Make an acronym plural by adding an “s” at the end, but not an apostrophe.
acronyms
Incorrect Correct

TPD’s TPDs

RSD’s RSDs

Plurals of single Make a single letter plural by adding an apostrophe and an s. Italicize the
letters letter, but do not italicize the apostrophe or the s.

Incorrect Correct

ys y’s

x’s x’s

Plurals of numbers Make a number plural by adding an s at the end, but no apostrophe.

Incorrect Correct

1990’s 1990s

290’s 290s

Use numbers correctly


Numbers are good vehicles for conveying information, but can cause
confusion and inaccuracies if not used correctly.
For information about watching agreement in number, see “Watch agreement
in number” on page 21.
Use the following guidelines when working with numbers in your
documentation:

Avoid using exact numbers when possible. For example, use the
following construction:
This task can be performed in the following ways...
instead of saying something similar to, “Use one of the three following
ways to complete this task.” Being imprecise in this case ensures the
accuracy of the text, even if the documentation or software is revised.

Use numerals for all steps in procedures.

34 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Accurate 1
 Use numerals for any number 10 and greater in body text. Spell out
numbers less than 10. On the first reference, spell out the word and then
enclose the numeral in parentheses. For example, “If the inmate’s
account balance is zero (0), then the account can be closed.” For
subsequent references, spell out the number.
 Use numerals for all examples of data input or display, including
numbers less than 10. For example, if the reader is to enter a one in a
field, present the information as “In the Value field, enter 1.”
 Use numerals for all measurements, regardless of whether the
measurement is spelled out, abbreviated, or replaced with a
symbol. Measurements include distance, points, size, temperature,
volume, and weight, but not units of time.
 Use numerals for screen resolutions, using the format number ×
number. Use the Alt key combination Alt+0215 to create the x. For
example, 640 × 480.
 Use numerals for examples of phone numbers and fax numbers.
Use the prefix 555. Use the Microsoft style format of (xxx) xxx-xxxx.
For example, (435) 555-1234.
 Use numerals for examples of Social Security Numbers. Use the
prefix 999. For example, 999-33-4567.
 Avoid starting a sentence with a number. If the sentence must begin
with a number, then spell out the number, no matter how large.
 When comparing numbers, use more than or less than rather than
over or under. Use over and under for spatial relationships.
 Use commas in numbers with four or more digits. The following
cases are exceptions:
– Page numbers
– Addresses
– Decimals
– Years
Commas in years are acceptable if the year has five or more digits,
which is a rare occurrence in Spillman documentation. The following
table shows examples of commas used correctly with numbers. For
more information about commas, see “Using commas” on page 109.

Correct examples

2,500 calls per month 1207.34 average calls per month

Documentation Department Writing and Style Guide 35


Basic Rules of Technical Writing
1 Be Accurate

Correct examples

page 1112 January 1, 1987

10234 S. Redwood Road 10,000 B.C.


Make a number plural by adding an s but no apostrophe, such as
the 1990s. For more information, see “Correctly spell plurals” on
page 33.

Use an en dash to indicate a range of number or a negative
number. For more information, see “Using en dashes” on page 111.

36 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Precise 1

Be Precise
All documentation must be precise to avoid misunderstanding and possible
user error. Spillman documentation is designed to answer questions for
readers, not to create questions. Be specific about how to perform procedures,
and be clear about where things are located on the screens.
Use the following guidelines to help ensure precision in your documentation:
 “Interpret facts” on page 37
 “Correct misplaced modifiers” on page 38

“Avoid vague wording” on page 39
 “Use the correct article” on page 39
 “Be aware of implications” on page 40
 “Be aware of connotations” on page 41
 “Use prepositional phrases instead of possessives” on page 44
 “Use symbols correctly” on page 45

Interpret facts
In conversation, people interpret facts and stories, rather than stating facts. In
writing, the temptation can arise to state the facts rather than interpreting
them. Compare the following ways of presenting information.

Stating facts Interpreting facts

Several Utahans are vying for a seat in the Several Utahans are vying for the United
United States Congress. Jim Hansen served State Congressional seat that will be left
in the United States Congress for 22 years. vacant when James V. Hansen retires at the
He represented Utah. Congressman James end of his current term.
V. Hansen announced that he will retire at
the end of his current term.

Do not name the zone theme the same as the Do not give the zone theme the same name
zone table. When you create the zone as the zone table. If the zone theme and the
theme, the software generates a zone zone table have the same name, then the
attributes table for that theme. You do not software cannot distinguish the zone table
use this table in your zone table. The from the zone attributes table that the
following sections describe how to create a software generates for the zone theme. If the
zone table. If you name the theme and the software cannot distinguish between the two
zone table the same, the software cannot tables, then the software stops responding
distinguish the two tables. This causes the when the Create Zones script is run. The
software to stop responding when you run following sections describe how to create a
the Create Zones script. zone table.

Documentation Department Writing and Style Guide 37


Basic Rules of Technical Writing
1 Be Precise

Notice that in both stating facts examples, the topic is attacked from two
directions. In the first example, the focus abruptly switches from several
Utahans vying to Jim Hansen served. In the second example, the focus on
why the zone theme should not have the same name as the zone table is
interrupted by the statement about what the following section contains. In
both interpreting facts examples, the focus remains on one idea.
Stating facts can lead to attacking a topic from two directions, while
interpreting facts keeps the focus on one idea. Interpreting facts also often
leads to tighter writing.
Part of interpreting facts is deciding what facts can be left out. In technical
writing, the history of the software or the reasons for the design are not
necessary. If the information is not needed to help readers perform a task, then
do not include it.

Correct misplaced modifiers


Modifiers are words, phrases, or clauses that modify a noun, a verb, or other
modifier. Be careful to place modifiers so that they are clearly connected with
the words that the modifiers are intended to modify. The following table lists
examples of misplaced modifiers and explains why the misplacement is a
problem.

What the Incorrect


Incorrect Correct
Version Implies

In Yuba City, you can learn That the criminal justice In Yuba City, use the Stolen
whether a particular vehicle, agency stole a vehicle, Vehicle System (SVS) to
vehicle license plate, or license plate, or part, and learn whether a criminal
vehicle part has been used the SVS to do it. justice agency has reported
reported stolen by a crimi- a particular vehicle, vehicle
nal justice agency using the license plate, or vehicle part
Stolen Vehicle System stolen.
(SVS).

Do not add a common place That it is acceptable to use Do not use the Locate
directly to the map using the the Locate Address tool to Address tool to add a
Locate Address tool. indirectly add a common common place directly to
place to the map. the map.

In the Item field, enter a That the watch is worn by In the Item field, enter a
description of the item, such gold-colored males. description of the item, such
as gold men’s watch. as men’s watch,
gold.

In the Item field, enter a


description of the item, such
as men’s gold watch.

38 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Precise 1

The word only is an easily misplaced modifier, and the meaning of a sentence
changes dramatically depending on where only is placed. Only I eat
chocolate, I only eat chocolate, and I eat only chocolate use the same words,
but the meaning is different in each sentence. Make sure that the word only is
placed next to the word it is modifying. Phrases that start with the word with
also frequently result in misplaced modifiers.

Avoid vague wording


The word use often appears in vague text. Watch for it and other words that
can signal that the documentation is not as precise or clear as it should be.

Incorrect Correct

Use the Commands menu to dispatch a Select Command > Dispatch Call to
call. dispatch a call.

When talking about people in documentation, substitute the appropriate,


specific noun rather than using individual or person when possible. For
example, inmate, offender, victim, or suspect.
The phrase receive a message is vague. Always indicate the means used to
present the message, such as The Names screen displays the following
message... or The interface sends the SAA an email.
Be careful with vague words such as this and these. The words this, these,
that, and those are pronouns that often have vague antecedents when used
alone. Most of the time, it is better to use these words as demonstrative
adjectives, rather than as pronouns. Use these terms to modify other terms that
clearly convey your meaning. For example, Make sure to save the record
after completing each tab. This action helps prevent data loss.

Use the correct article


In English, articles are adjectives that denote definitiveness. The article the
implies a specific noun, sometimes one that has already been referred to. The
article a/an implies a nonspecific noun. For example, “I saw a dog yesterday”
means something different from “I saw the dog yesterday.” The first sentence
implies seeing a random or unknown canine, while the second sentence
implies seeing a specific canine, possibly already known to the speaker and
hearer.

Documentation Department Writing and Style Guide 39


Basic Rules of Technical Writing
1 Be Precise

The article a/an can also imply the existence of more than one of the
accompanying noun. For example, “Would you like to buy a puppy?” implies
the existence of puppies that would not be bought. If there was only one
puppy for sale, then the question “Would you like to buy the puppy?” would
be more clear.
In your documentation, misused articles that imply the existence of
nonexistent things can confuse readers and cause statements to be inaccurate
and unclear. For example, the statement A Call Comments dialog box opens
implies that there is more than one Call Comments dialog box. Readers can
wonder if they opened the correct Call Comments dialog box. In reality, there
is only one Call Comments dialog box, so the statement The Call Comments
dialog box opens is correct.
Repeat articles as necessary to make sure the correct form of an article is use
with each noun. For example, an assault or a homicide, not an assault or
homicide.

Be aware of implications
Much of what is communicated between people, no matter the medium, is
implied or inferred. In technical writing, it is impossible to know the
background and thinking patterns of all readers. Therefore, each word must be
examined to ensure that the word, by itself and as part of a phrase, clause, or
sentence, does not imply anything that is untrue, inaccurate, or confusing. In
the sentence The following is an example of a generated tbzones table, an
unnecessary adjective implies that there is more than one way to create a
tbzones table, which is not true. This implication could leave readers confused
or misled.
Another example of imprecise wording that can imply untruths is the
mislabeling of alias records as Alias records. In Spillman documentation,
records that are stored on a specific table are labeled with a capital letter, such
as Name records or Vehicle records, to distinguish them from other types of
records. All alias records are entered as Name records, but calling the records
Alias records implies the existence of a table just for alias records, even
though there is not such a table. For absolute clarity, use wording such as
Open the Name record for the person’s alias.
Another phrase to avoid because of possible implications is change the
default. Rarely is it correct to state that users are changing default values or
information. The users change the value or information when they do not
want to use the default values, but (in most cases) the default value remains
the default. On rare occasions, administrators do actually change a default
setting. In these cases change the default is correct.

40 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Precise 1

A final example of the need to be aware of implications is the phrasing the


software takes readers somewhere. Obviously, when a person uses a
computer, the software does not move the user somewhere. Therefore, the
software cannot take readers anywhere. Use the words opens, appears, or
displays to describe what happens on the computer monitor. For more
information, see “Choose the correct word” on page 73.

Be aware of connotations
In speech and casual writing, some words are used as synonyms, even when
the words have different connotations, or secondary meanings. Technical
writing cannot be ambiguous in word choice. The following table lists some
words to be careful not to confuse.

Words to watch Connotations to consider

additionally, in addition Additionally, as an adverb, should not be used to


modify a sentence. Use in addition instead.

another, different Another can mean “an additional thing” as well as “a


different thing.” Replace another with different when
“different” is the intended meaning.

backup, back up Backup is a noun or adjective, meaning “an extra


copy.” Back up is a verb, meaning “to make an extra
copy.”

because, since, as Because always means “for the reason that, or due to
the fact that” while since and as have other meanings.
Since often implies the passage of time, rather than a
reason, and as can mean “similar to” or “for
example.” Use because when stating reasons.

can, may, might Can means both “able to” and “allowed to” to most
people. May is more open to other meanings,
including uncertain possibilities, and should be
avoided. Use might to indicate a possibility.

copy-and-paste, copy and paste The adjective is copy-and-paste. The verbs are copy
and paste. Avoid using the adjective if possible.

cut-and-paste, cut and paste The adjective is cut-and-paste. The verbs are cut and
paste. Avoid using the adjective if possible.

current date, today’s date Today’s date can imply the date the document was
written, not the date the document is being read. Use
current date in all cases.

convicted of, convicted for Convicted for implies guilt, which is not a judgment
that needs to be made in technical writing. Use
convicted of in all cases.

Documentation Department Writing and Style Guide 41


Basic Rules of Technical Writing
1 Be Precise

Words to watch Connotations to consider

discuss, presents, explains, Avoid stating that a document discusses a topic. A


describe discussion requires at least two people, and a
document is not a person. Use presents, explains or
describes instead.

different from, different than Use different from. As The Elements of Style points
out, “logic supports established usage: one thing
differs from another, hence, different from.”

either Use either when presenting only two alternatives. If


more than two alternatives exist, simply state them
without using either.

ensure, make sure Ensure is used to indicate that an indirect action


guarantees the result, while make sure is typically
used in cases where users are being instructed to
perform a direct action. For example, “Make sure to
run the Jail Merge program on a regular basis to
ensure that your database does not contain duplicate
Inmate records.”

felony, misdemeanor A felony is a serious crime. A misdemeanor is a minor


offense against the law. A fuller definition of what
constitutes a felony or misdemeanor depends on the
governmental jurisdiction involved. A felon is anyone
convicted of a felony, regardless of whether the person
is fined, given probation, or spends time in
confinement.

fewer, less In general use fewer for individual items. Use less for
bulk or quantity. For example, “Because Jane has
taken fewer classes this semester, she has felt less
stress.”

generally, in general Generally, as an adverb, should not be used to modify


a sentence. Use in general instead.

install, installation Install is a verb. Installation is a noun or adjective.

must, need to Must implies that the thing should be done so that
something else can be done, or that something else
will be negatively affected if the task is not completed.
Need to can imply a life-or-death situation, which is
more dramatic than accurate. In most instances, use
must instead of need to.

open, display, access. For records, readers open them, not display them or
access them. For more information, see“Choose the
correct word” on page 73.

42 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Precise 1

Words to watch Connotations to consider

prison, jail Prisons normally confine people who are serving


sentences for felonies, while jails normally confine
people who are serving sentences for misdemeanors,
are awaiting trial or sentencing, or are confined for
civil matters, and will be there for a year or less. Most
Spillman customers run jails.

read-only, view-only Read-only is for files that cannot be changed.


View-only is for fields and tabs that cannot have
information entered or changed by the user. Both
words are adjectives, and should be hyphenated
whether they are used before or after the noun.

should Avoid using should, which leaves room for doubt. For
example, After clicking Save, the record should be in
the database can leave users wondering if there are
instances where clicking Save would not result in the
record being in the database.

setup, set up Setup is a noun or adjective, meaning “arrangement,


organization.” Set up is a verb, meaning “to
assemble.”

upper left, upper right When using left and right as nouns, as in “On the
lower left, lower right upper right, a list is displayed,” do not use a hyphen.
upper-left, upper-right When using upper-left or lower-right (or their
lower-left, lower-right counterparts) as adjectives, use a hyphen. For
example, “In the upper-right area, a list is displayed.”

The left half of the screen is the portion in front of the


user’s left arm. The right half of the screen is the
portion in front of the user’s right arm.

Washington Because of the need to differentiate between


Washington, the state, and Washington, as in the
District of Columbia, use state of Washington or
Washington state. Use Washington DC or District of
Columbia for the nation’s capitol. For other states,
simply use the state name.

Documentation Department Writing and Style Guide 43


Basic Rules of Technical Writing
1 Be Precise

Words to watch Connotations to consider

with, by using, containing, has With can mean “containing” or “by using” or
“who/that has,” but it also can mean “together, at the
same time, accompanying.” Therefore, for clarity, use
by using or containing, or (user/thing) who/that has if
that is the intended meaning.

whether, if Do not use if to mean whether. Words such as see,


determine, and learn generally should be followed by
whether.
To determine whether if is being used correctly,
transpose the clauses. If the sentence still makes
sense, then if is used correctly. For example, consider
the following sentences:
• The Cross Streets field displays the cross streets
nearest the address if the gbcross application
parameter is set to ON.
• The Security chapter can help determine if
password protection should be used.
Now, consider the transposed sentences:
• If the gbcross application parameter is set to ON,
then the Cross Streets field displays the cross
streets nearest the address.
• If password protection should be used, then the
Security chapter can help you determine.
The first sentence uses if correctly and can be written
with either version. The second sentence should use
whether, and must be written using the first version.

Use prepositional phrases instead of possessives


In most cases in technical writing, it is best to avoid using possessives.
Apostrophes clutter a clean page, and it can be confusing what the possessive
is referring to. Use prepositional phrases instead of possessives. However, if a
series of prepositions makes the text long and confusing, then substitute a
possessive as needed.
When using prepositions, avoid ending the sentence with one. However,
clarity and flow are more important than holding to this guideline.

44 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Precise 1

The following table shows examples of incorrect and correct use of


possessives.

Incorrect Correct Notes

Column 1’s totals The totals in column 1. Making a number


possessive is never the
cleanest way to write.

If the value in the Date If the record’s Date Too many prepositional
Recov/Rcvd field of the Recv/Rcvd value is within phrases stacked on top of
record is within the date the date range specified on one another leads to
range specified in the the Report screen, then... confusion about which noun
Report screen, then... the phrases are modifying.

On the rare occasion when Spillman Technologies needs to be used as a


possessive, omit the s that normally follows the apostrophe when making a
singular noun possessive. For example, “Spillman Technologies’ employees”
is correct. However, most of the time, “the employees of Spillman
Technologies” is the better construction.
Include the s when forming the possessive of other singular words that end in
s. For example, “the California Department of Motor Vehicles’s database” is
correct.

Use symbols correctly


Symbols are efficient ways of conveying information that is common or long,
but only if they are used precisely so that readers know what the symbol
means. The Spillman software uses symbols throughout. In documentation,
writing out the word is cleaner and more professional.
On the first reference to a symbol, spell out the word and then enclose the
symbol in parentheses. For example, “If a required field is missing
information, then an exclamation point (!) appears next to the field.”
If the symbol is a parenthesis, then set it off with a comma. For subsequent
references, except in samples of data entry or display, spell out the name of
the symbol.
It is acceptable to use symbols without spelling out the word when
documenting websites, email addresses, and currency values.

Documentation Department Writing and Style Guide 45


Basic Rules of Technical Writing
1 Be Precise

The following table lists common symbols, their names, and their keyboard
shortcut.

Symbol Name Shortcut

! Exclamation point Shift+1

@ At symbol Shift+2

# Pound sign (not hashtag) Shift+3

$ Dollar sign Shift+4

^ Caret Shift+6

& Ampersand Shift+7

* Asterisk Shift+8

( Open parenthesis Shift+9

) Close parenthesis Shift+0

- Hyphen Hyphen (between 0 and =)

_ Underscore Shift+Hyphen (-)

= Equals sign Equals Sign (between - and


Backspace)

+ Plus sign Shift+Equals Sign (=)

[ Open bracket Open Bracket (next to P)

] Close bracket Close Bracket (between [ and \)

{ Open brace Shift+Open Bracket ([)

} Close brace Shift+Close Bracket (])

\ Backward slash Backward Slash (above Enter)

| Pipe symbol Shift+Backward Slash (\)

; Semicolon Semicolon (next to L)

: Colon Shift+Semicolon (;)

’ and ‘ Apostrophe or single quotation mark Apostrophe (next to Enter)

, Comma Comma (next to M)

. Period Period (between , and /)

< Less-than symbol Shift+Comma (,)

> Greater-than symbol Shift+Period (.)

/ Slash Slash (next to Shift)

46 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Precise 1

Symbol Name Shortcut

? Question mark Shift+Slash (/)

© Copyright Alt+0169 (on the number pad)

° Degree Alt+0176 (on the number pad)

— Em Dash Alt+0151 (on the number pad)

– En Dash Alt+0150 (on the number pad)

× Multiplication sign Alt+0215 (on the number pad)

® Registered trademark Alt+0174 (on the number pad)

™ Trademark Alt+0153 (on the number pad)

Documentation Department Writing and Style Guide 47


Basic Rules of Technical Writing
1 Be Thorough

Be Thorough
Your documentation must be thorough. Think about how frustrating it would
be to look through a manual and not find any information on an important
feature, or to find a reference to a feature but not have it clearly explained.
Readers do not want to experience that frustration.
Being thorough also helps make sure your documentation is accurate and
precise.
When researching for documentation, analyze the project or product in terms
of tasks that readers want or need to accomplish using the software.
Document all necessary tasks, and consider the specific effects that the
products have on readers. The procedures themselves must also be thorough.
Even though your documentation must be thorough, not every detail of the
software must be laid out. Focus on what the reader needs to know. For
example, if there are five ways to complete a task, then find out which one or
two ways are the most common, and document only those ways.
Documenting too many ways encumbers the documentation and might
confuse the reader.
Use the following question words to be thorough in your documentation:
 Who? Who must perform the task? Is it an administrator, a user, or a
Spillman employee?
 What? What is the task? What conditions must the task be performed
under? What happens if the person fails to perform the task? What
additional tasks might be required?
 Where? Where is the task performed? In a vehicle, office, or dispatch
center? On the server or client machine?

When? When should the task be performed? During installation? After
an upgrade? After or before another task is performed? Routinely as
part of maintenance? Can parts of the task be delayed or should it all be
completed at once?
 How? How is the task performed? From the user’s computer? From the
server? In chunks? Can the task be automated or simplified with
settings? Is the task a repeated task or a one-time process?
 Why? Why should the task be performed? Why should readers know
this information? If the answer is “maybe readers do not need to know
this information,” then consider excluding the information from the
manual.

48 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Thorough 1

Research is perhaps the most creative part of technical writing. It is your


opportunity to imagine what might have been omitted from the design
description, and how the software can be improved. Be the readers’ advocate.
Find out what tasks are vital for readers to know about so that the software
works for their agency.
One research technique is to question every occurrence of passive voice in a
design document. As the developer or designer fills in the action verbs and
nouns, many clarifications appear, and other important questions can be
raised.
Another good research technique is to question vague phrases such as “if
available.” Available where? Available to whom? Available under what
conditions? Available why? Is the data available because a user entered it? Is
it available if the software does something in particular? Answers to these
questions make the documentation better.
Two good sources of information about products are Research Specification
Documents (RSDs) and Technical Product Documents (TPDs).

Documentation Department Writing and Style Guide 49


Basic Rules of Technical Writing
1 Be Concise

Be Concise
Your documentation must be concise. No one reads technical writing to be
entertained or awed by sentence construction. Readers want information
quickly and without pondering.
Do not sacrifice accuracy, precision, or thoroughness for concision.
Use the following guidelines to keep your documentation concise:

“Think about the needs of readers” on page 50

“Avoid big, pompous-sounding words” on page 50
 “Keep your sentences and paragraphs short” on page 54

“Avoid redundancy and repetition” on page 54

“Cut unnecessary words” on page 56

Think about the needs of readers


Readers do not need every feature of the software documented. Present only
the information readers need. If a feature changes, then do not document what
the software used to do. Document what the product does now. If a change to
the software is drastic, then it might be appropriate to point out the change.
Check with the development team and the Documentation department
manager when documenting changes that might be drastic.
The only exception to this guideline is when Short Enhancement documents
(SEDs) are written, which are designed to help readers understand what
changes occurred in the software with an enhancement.

Avoid big, pompous-sounding words


Some readers have strengths in areas other than the written word. Your
documentation should never make them or anyone else feel stupid or
uneducated. Do not use big, pompous-sounding words or phrases.
Big, pompous-sounding words and phrases can also hide the simple meaning
of the documentation. Another reason to avoid big or pompous-sounding
words or phrases is that they can be used by writers who are trying to
convince themselves that they know what they are talking about, even when
they do not.

50 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Concise 1

The following table lists common big or pompous-sounding words and


phrases, and their smaller, better alternatives. Some of these words are
acceptable if they are the official term used in the software, or in manuals
written for administrators, who might be more likely to understand technical
jargon.

Replace this word or phrase With this word or phrase

abbreviate shorten

abort cancel

accordingly so

activate start

aggregate total, whole

anomalous not normal, abnormal

antithesis opposite

ascertain find out, discover

autonomous independent

beverage drink

cessation stop, pause

commence begin

commencement start, beginning

component part

comprise compose, make up

concept idea

concur agree

configuration shape, design, setup

conjecture guess

contiguous near, touching

currently now

deficit shortage

demonstrate show

discourse talk

disengage fire, stop, pull/push apart

duplicate copy

Documentation Department Writing and Style Guide 51


Basic Rules of Technical Writing
1 Be Concise

Replace this word or phrase With this word or phrase

eliminate cut out, delete

elucidate clarify

etcetera and so on, including


(Do not use the abbreviation etc. either.)

exhibit show

expedite hasten, hurry, speed

facilitate ease, simplify, help

feasible possible, likely

fracture break

function work, act

gradient slope

homogeneous uniform, similar

impairment injury, harm

in isolation alone, by itself

incinerate burn

incision cut

incombustible fireproof

indubitably doubtless, definite, definitely

inform tell

initiate begin

inundate flood

locate find

maintenance upkeep (Maintenance is acceptable as a technical


term in administration manuals.)

major main, chief

manufacture make

minuscule tiny, small

moreover besides

necessitate require, need

necessity need, requirement

52 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Concise 1

Replace this word or phrase With this word or phrase

nomenclature name, system of terms

obtain get

optimum best, preferred

orientate orient

paramount main, chief

perspective view

posterior rear

potent powerful, strong

potentially possibly, possible

practically nearly, most, all but

prior to before

purchase buy

ramification result

request ask

requisite needed, necessary

segregate set apart, separate

sophisticated complex

subsequent next

sufficient enough

terminate end, stop

transmit send

utilization use

utilize use

verification proof

viable workable

visualize imagine, picture

Documentation Department Writing and Style Guide 53


Basic Rules of Technical Writing
1 Be Concise

Keep your sentences and paragraphs short


Most of your sentences should be simple sentences. Do not avoid complex
sentences completely because doing so can make your writing sound childish.
However, using many dependent clauses and appositive phrases can make
your sentences confusing and difficult to follow. Avoid using semicolons to
join independent clauses.
Normally, your paragraphs should be between three and eight sentences in
length, and around 50 words. Solid blocks of text are intimidating to most
readers.

Avoid redundancy and repetition


Each paragraph, sentence, and word should add something new to the
documentation, not repeat something that has already been stated.
Some common phrases are redundant. For example, old adage is redundant
because the definition of adage is “old saying.”
Some words are redundant when paired with an adjective. For example,
saying something is very unique is redundant because the definition of unique
is “one of a kind” and something cannot be “extremely one of a kind.”
Sometimes your writing might not be redundant in the literal definition of the
word, but a concept or word might be repeated to the point that the writing
feels redundant. Remember to look at the writing and find ways to not repeat
words or concepts.
Avoid redundancies by asking what a particular word or phrase adds to the
meaning of your documentation. If the word or phrase does not add anything,
then it is probably redundant. The following table lists common redundant
words and phrases and their substitutes.

Replace this word or phrase With this word or phrase

absolutely essential essential

absolutely perfect perfect

actual experience experience

add a new (record) add a (record)

adding together adding

advance plan plan

all of, all of these all

an honor and a privilege an honor

54 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Concise 1

Replace this word or phrase With this word or phrase

any and all any

balance against one another balance

basic essentials essentials

brief overview overview

by means of by

cancel out cancel

check to see if see whether

combine into one combine

consecutive in a row consecutive

continue on continue

cubic meters in volume cubic meters

current status status

different varieties varieties

drag and drop drag (Dragging an item somewhere implies


releasing it as part of the action.)

each of, each of these each

equally as well equally

final outcome outcome

first and foremost first

first introduction introduction

first priority priority

goals and objectives goals

honest truth truth

in between between

in close proximity close

isolated by himself isolated

joined together joined

main essentials essentials

mixed together mixed

mutual cooperation cooperation

Documentation Department Writing and Style Guide 55


Basic Rules of Technical Writing
1 Be Concise

Replace this word or phrase With this word or phrase

necessary requisite necessary

one and the same the same

open up open

overall plan plan

past history history

personal opinion opinion

physical size size

point in time time, now

rain shower rain, shower

reason why reason

refer back to refer to

repeat again repeat

share the same share

some of, some of these some

small in size small

take action act

this particular instance this instance

this particular time now

triangular in shape triangular

true facts facts

whether or not whether

Cut unnecessary words


Many words are filler words or “fluff,” which are often used to expand the
length of a document, or to make the writer sound knowledgeable. Technical
writing does not need fluff. Therefore, if the document loses no meaning
when a word, phrase, or sentence is removed, then remove it.
The following table lists examples of common ways to cut unnecessary
words, phrases, or sentences.

56 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Concise 1

Fluff version Better version Comments

There are three ways to do this. Use To do this, use one of the There is/are is a weak way to begin a
the following ways to do this: following ways: sentence. Often, the sentence can be reworked
to not include there. In general, there is fluff.

After you make the changes in the The changes made in ArcView If a concept can be explained using only a
ArcView, they appear in the software appear in Spillman the next noun, instead of a noun and a pronoun, use the
the next time you run the Create time the Create Text noun-only construction.
Text Files script. Files script is run.

Select any of the line drawing tools. Select any line drawing tool. The phrase of the can be fluff. Use adjectives
instead of adding a prepositional phrase.

If the street changes directions, draw If the street changes directions, Watch the number of adjectives used to
two separate streets. then draw two streets. describe something. Make sure they are not
synonyms, or imply the same thing. In this
example, two and separate are not synonyms,
but the definition of two implies that the
things are separate.

The Select All command and the Use the Select All and Undo The process of is often a sign of weak writing
Undo command can help to speed the commands to quickly edit your and fluff.
process of editing your message. message.

The software automatically fills in the The rest of the fields are If the user is not doing something, then it is
rest of the fields on the screen. automatically populated. often obvious that the software is doing it,
especially if the process is described as
automatic. Do not use the phrase the software
with the words automatically or generated.

The software generates a record The record number is If all the steps of a process can be described in
number and enters it in the Name automatically populated in the a word or phrase, then do not describe them
Number field. Name Number field. with their own words.

The following illustration shows a The following example shows This example shows a particularly nasty type
generated tbzones table. the tbzones table. of fluff that actually implies an untruth. In this
example, the concern is that generated implies
that the tbzones table can be created by
another means, which it cannot be.

The name that is in the First field on The name in the First field on That is is often a sign of weak writing and
the Names screen is displayed on the the Names screen is displayed fluff.
report. on the report.

In order to add a record, a search for To add a record, first perform In order to is nearly always a sign of weak
matching records must be performed a search for matching records. writing and fluff. Use to on its own.
first.

The software does not allow you to Records cannot be added until Sometimes, writers use long phrases when a
add a record until after a search is a search is performed. shorter phrase or single word has the same
performed meaning. In this example “the software does
not allow you to” can be shortened to “this
cannot be done.”

Documentation Department Writing and Style Guide 57


Basic Rules of Technical Writing
1 Be Concise

Fluff version Better version Comments

It is impossible to create two access It is impossible to create two Although whose is a possessive for who, and
records the only difference in which access records whose only generally is not used when referring to things,
is the system access level. difference is the system access occasional exceptions are acceptable. For
level. concision, use whose when referring to things
as needed.

Inmate records are connected to The Inmate record is the key If your copy includes the phrase in other
nearly every other record type in the record for any incarceration, as words or this means, then the information is
Jail module. In other words, the it is connected to nearly every not being presented as clearly as it could be.
Inmate record is the key record for other record in the Jail module. Sometimes, the extraneous phrase can simply
any incarceration. be removed, but more often, it is better to
consider rewriting the information. Do not use
the expressions this means or in other words.

58 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Consistent 1

Be Consistent
Consistency is vital in technical writing. It builds readers’ trust in the
documentation, and makes scanning easier because they know what to expect.
Use the following guidelines to maintain consistency in your documentation:
 “Use terminology and formatting as markers” on page 59
 “Present information in the same order” on page 59
 “Use parallel structure” on page 60
 “Use common abbreviations” on page 60

“Use alphabetization” on page 63

Use terminology and formatting as markers


Always use the same terminology to refer to buttons, menus, and other items
on the screen. For example, calling a CAD command format anything else,
such as a usage or syntax, confuses readers and makes it difficult for them to
find what they are looking for. Use the terminology in the software, unless
changes are needed for clarity.
Consistent formatting, including capitalization, provides readers with visual
clues about what information is included in a section. Formatting particularly
helps readers who are scanning the document. Always format all components
in a document consistently, and follow Spillman formatting guidelines for all
documents to maintain formatting across all Spillman documentation.
For more information, see “Formatting” on page 65.

Present information in the same order


The order information is presented in should be consistent at all levels, from
headings to bulleted lists. For example, if your documentation describes two
screens, and readers can add, modify, and delete records on both screens, then
describe adding, modifying, and deleting in the same order in both sections.
Other places where the consistent order of presentation is particularly
important include the following:
 When items are called out on an image and then described. Match
the description order to the order the items were called out. If
necessary, reorder the callouts or the descriptions.

When a bulleted list is used to summarize the sections to follow.
Match the order of the bulleted items to the order of the sections.

Documentation Department Writing and Style Guide 59


Basic Rules of Technical Writing
1 Be Consistent


When there are multiple ways to perform a task. Match the
description order to the order the methods are listed.

Use parallel structure


Parallel structure is a powerful tool in all writing, including technical writing.
Parallel structure is defined by the Purdue University OWL as “using the
same pattern of words to show that two or more ideas have the same level of
importance.” Parallel structure works at the word, phrase, clause, and
document level. Places where parallel structure works particularly well
include the following:

Headings of the same level. All headings at the same level in a section
should be parallel. For example, “Adding a Record,” “Modifying a
Record,” and “Deleting a Record,” not “Add a Record,” “Modifying
Records,” and “Delete Records.” For more information, see
“Formatting Headings” on page 101.
 Items in a bulleted list. Every item in a bulleted list should start with
the same type of word, normally a noun or verb. The items in the list
should also be either all complete sentences or all incomplete
sentences. For more information, see “Formatting Bulleted Lists” on
page 87.

Callouts for a image. Every callout for an image should match in
construction. For more information, see “Formatting callouts” on
page 73.
The items in the above list are examples of parallel construction. All three
bullets start with a plural noun and then use a prepositional phrase to describe
the noun. If the second item said bulleted list items instead, then the list would
not use parallel structure, and the rhythm and expectation of the information
would be lost.

Use common abbreviations


Abbreviations, including acronyms, are efficient ways of conveying
information that is common or long, but only if readers know what the
abbreviations stand for. Abbreviations must be used consistently to have any
power.

60 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Consistent 1

The first time an abbreviation is used, write out what the abbreviation stands
for, and then add the abbreviations in parentheses after. For example,
“Depending on the way your Spillman Application Administrator (SAA) has
set up the software....” Subsequent references can use only the abbreviation.

NOTE
For the Spillman Release document (SRD) and short enhancement documents
(SEDs), it is acceptable to use an acronym or abbreviation without explaining it, if
that abbreviation is thoroughly explained in the full documentation of the module.

For example, in an SED, “CAD” can be used without defining it, as the term is
fully explained in the CAD manuals.

However, if no manual exists that explains the term, then the SRD and SED must
follow the same rules as the manuals, and write out the abbreviation. For
example, when a new interface is documented, the SED will become the only
manual for the interface.

An exception to this rule is the term FBI. Always use the abbreviation without
writing out the term. Other exceptions might exist, such as common words,
including DVD or CD.
Table names, such as apparam, are not acceptable “abbreviations” of official
terms, such as application parameter. In administrator documentation, after
the first use, it might be appropriate to call a table by its shorter software
name. For example, calling the Official Names Codes table the apnames
table. This convention is not appropriate in user documentation. For more
information, see “Formatting Documentation” on page 67.
If a term is not used often in the documentation, then it might be appropriate
to write out the term each time instead of using an abbreviation, especially in
long documents that readers are not reading cover to cover.

TIP
In general, it is a good idea to use both the proper name and the table name the
first time the term is used in a section. For example, using the Administration
Manager (adminutil). Thereafter, within that section, it can be the proper name
or the table name as long as it is consistent. If stipulating both terms per section
becomes too redundant, then use the proper name. It is better to use the proper
name alone (Administration Manager) than the table name alone (adminutil).

Make an acronym plural by adding an s, but not an apostrophe. For example,


SAAs. For more information, see “Make sure plurals and singulars are
correct” on page 32.

Documentation Department Writing and Style Guide 61


Basic Rules of Technical Writing
1 Be Consistent

The following table lists some common abbreviations used in Spillman


documentation, as well as some terms that should not be abbreviated.

Term Abbreviation Notes

Time formats A.M. P.M. Always use the time formats presented in
the software. Some parts of the software
use 24-hour format, while others use
A.M. and P.M.

computer-aided dispatch CAD It is acceptable to use the CAD


abbreviation in a heading directly before
the term is introduced.

days Do not abbreviate.

dots per inch DPI For more information, see “Use screen
shots” on page 70.

etcetera etc. Do not use the term or the abbreviation.


Design documents might use either.

feet ft or ‘ Use the symbol only if necessary for


space constraints.

for example, such as e.g. or i.e. Do not use the abbreviations. Always use
for example or such as.

grains gr A unit of measurement for bullets,


gunpowder, and drugs.

hours Do not abbreviate

inches in. or “ Remember to add the period to the


abbreviation to distinguish between it and
the word in.
Use the symbol only if necessary for
space constraints.

miles mi No period.

millimeters mm Omit the space between the numeral and


the abbreviation when using in a
photographic context, as in 35mm film.

months Do not abbreviate.

records management RMS It is acceptable to use the RMS


system abbreviation in a heading directly before
the term is introduced.

seconds Do not abbreviate.

62 Documentation Department Writing and Style Guide


Basic Rules of Technical Writing
Be Consistent 1

Term Abbreviation Notes

Social Security Number SSN Some documents might not capitalize the
N in number. However, the Spillman
company style guide states that all words
should be capitalized in the term.

Spillman Application SAA Make sure Application is singular.


Administrator

United States U.S. Remember the periods.

weeks Do not abbreviate.

years Do not abbreviate.

Use alphabetization
Alphabetization helps readers locate information quickly, and makes editing
and revising documentation easier, especially when the responsibility for a
document is given to different writers. Therefore, arrange items, especially in
bulleted lists and tables, in alphabetical order as often as possible.
Do not let alphabetization trump logical organization or the order tasks must
be completed in. For example, even though the word deleting comes before
modifying alphabetically, it would not be logical to place a section about
deleting records before a section about modifying records.
Alphabetization can have two forms: word-by-word alphabetization or
letter-by-letter alphabetization. Spillman documentation uses word-by-word
alphabetization.
Word-by-word alphabetization orders multiple-word headings by word. If the
first two words of the headings match, then the second two words are
compared. The comparison continues until the words in the heading are
different. Letter-by-letter alphabetization treats multiple-word headings as
one long word and compares each letter in each heading. The following table
shows a list alphabetized in each way.

Word-by-word alphabetization Letter-by-letter alphabetization

soul soul

soul brother soulard crab

soul food soul brother

soul kiss souletin

soul mate soul food

Documentation Department Writing and Style Guide 63


Basic Rules of Technical Writing
1 Be Consistent

Word-by-word alphabetization Letter-by-letter alphabetization

soul music soulful

soul sister soul kiss

soulard crab soullessness

souletin soul mate

soulful soul music

soullessness soul sister

64 Documentation Department Writing and Style Guide


Chapter 2

Formatting

Jump to topic:
Introduction 66
Formatting Documentation 67
Formatting Voice 69
Formatting Bulleted Lists 87
Formatting Capitalization 88
Formatting Commands, Files, and Menu Items 94
Formatting Cross-References 96
Formatting Field Descriptions 98
Formatting Fonts 99
Formatting Headings 101
Formatting Line and Page Breaks 103
Formatting Numbered Lists and Procedures 105
Formatting Punctuation 107
Formatting Tables 116
Formatting
2 Introduction

Introduction
This chapter explains the formatting conventions used by the Spillman
Documentation department, and includes the following:

“Formatting Documentation” on page 67

“Formatting Voice” on page 69

“Formatting Bulleted Lists” on page 87

“Formatting Capitalization” on page 88

“Formatting Commands, Files, and Menu Items” on page 94
 “Formatting Cross-References” on page 96

“Formatting Field Descriptions” on page 98

“Formatting Headings” on page 101
 “Formatting Line and Page Breaks” on page 103
 “Formatting Numbered Lists and Procedures” on page 105

“Formatting Punctuation” on page 107
 “Formatting Tables” on page 116

66 Documentation Department Writing and Style Guide


Formatting
Formatting Documentation 2

Formatting Documentation
Spillman documentation is directed at two types of readers: users and
administrators. Users are the officers, dispatchers, and clerks who use at least
one part of the Spillman software to do their jobs on a daily basis.
Administrators are the people whose job is to set up and maintain the
functionality of the software.
In general, administrators are also Spillman Application Administrators
(SAAs), who have been trained by Spillman employees and are certified as
knowledgeable about the Spillman software. Some SAAs maintain the
software as their full-time job. However, administrators can also be
information technology personnel, or, for some small agencies, officers with
extra duties.
All documentation designed for SAAs and administrators should be separate
from user documentation—at a minimum in a separate chapter, or for bigger
modules in a separate manual.
All documentation, whether for administrators or users, should focus on the
tasks readers must complete. All documentation should also focus on what the
software currently does, not what it cannot do or what it did in previous
versions. If different versions of the software behave differently, then it is
appropriate to point out those differences.
The only exception to this guideline is when Short Enhancement documents
(SEDs) are being written. These documents are designed to help readers
understand what changes occurred in the software with the patch. When
integrating the SED into the manual, check with the development team and
the Documentation department manager to see whether a drastic change
should still be mentioned in the regular manual.

User In user documentation, avoid naming application parameters or settings when


documentation introducing feature or procedures controlled by that parameter. Instead,
guidelines describe the actions that occur because of the parameter value. Use wording
such as Depending on how your software is set up, one of the following
occurs... or Depending on the settings established by your SAA, a dialog box
might open... to let users know of differences that can be caused by
application parameters or settings.

Administrator In administrator documentation, provide a thorough explanation of all code


documentation tables, application parameters or settings, privileges, and any other special
guidelines setup or maintenance instruction for the module. The official Spillman
Application Administrator manuals provide definitions of code tables,
application parameters, settings, and privileges that affect the whole software
and how they are set up. Therefore, document only the setup and maintenance

Documentation Department Writing and Style Guide 67


Formatting
2 Formatting Documentation

tasks required for the specific module. Make sure to document the default
values of application parameters, settings, and environment variables.

68 Documentation Department Writing and Style Guide


Formatting
Formatting Voice 2

Formatting Voice
Consistent voice helps readers trust Spillman documentation and to learn the
“feel” of our company. Think about how fiction authors and songwriters have
a distinct voice, so much so that even if they were to release new material
without their name attached to it, it would still be possible to identify them as
the creator.
Spillman documentation should be that distinctive as well. Our customers
should recognize the company from the voice and style of the documentation.
Deviations from these conventions might not be grammatically incorrect, but
any deviation is still a breach of Spillman style.
Overall, Spillman documentation should sound like a friendly, professional
expert. It should be easy to read, but also thorough and technical. Use the
following guidelines to maintain the voice of your documentation:
 “Use the second person” on page 69
 “Use screen shots” on page 70
 “Choose the correct word” on page 73
 “Use explicit if-then statements” on page 84
 “Use coordinating conjunctions correctly” on page 85
 “Eliminate run-on sentences” on page 85
 “Use verbs correctly” on page 86

Use the second person


Use the second person with the understood you when writing Spillman
documentation. Using the second person creates more conversational, friendly
documentation, and helps ensure bias-free writing. Using the understood you
creates more professional documentation. In formal documentation, avoid the
word you unless something in the software, such as an error message, uses
you.
In more casual documents, such as tutorials, student handbooks, and online
courses, use of the word you is acceptable.
Older manuals use you. As these manuals are revised, the word you should be
removed.
It is appropriate to use the third person when referring to people other than the
reader, such as inmates, citizens, or, in administration manuals, officers. Most
of the time, use the generic “your agency” to refer to actions or decisions that
might be made by more than one person, such as “Follow your agency’s
policies about data entry when adding records.”

Documentation Department Writing and Style Guide 69


Formatting
2 Formatting Voice

Never give the specific name of an agency, except for the Springfield Police
Department, which is the standard Spillman example agency. Always add the
in front of a specific agency name, such as “The interface was created for the
Springfield Police Department,” not “The interface was created for
Springfield Police Department.”
Rarely is it appropriate to use first person. Do not use the first person when
referring to the company. Use Spillman or Spillman Technologies. When
talking about recommendations, use the phrasing It is recommended... instead
of We recommend or Spillman recommends.
First person is acceptable when giving an example of what users might enter.
For example, if in a tutorial users are being instructed to enter information in
the Comments field, then it would be appropriate to write, “In the Comments
field, enter I saw the suspect go into the house through the
back window.”

Use screen shots


As the adage goes, “A picture is worth a thousand words.” In technical
writing, images or screen shots are tools to help readers see what is being
described and to confirm the section explains what they are interacting with in
the software. Using screen shots also helps break up long chunks of text.
Use the following guidelines when adding screen shots to your
documentation:
 Screen shots should be used sparingly, and should never overpower the
documentation.
 The data in screen shots should be representative of what readers will
actually see in the software. Data should be realistic, bias-free, and
spelled correctly. Do not include data that has not yet been explained in
the documentation.

Screen shots should be limited in detail to help with maintenance.

Generally, screen shots should be images of screens, detail windows,
and dialog boxes. Avoid screen shots of menus and buttons, except for
in reference sections.

Screen shots should not have the mouse pointer in them. Most image
capture software has an option to hide the mouse pointer.

Save screen shots as Portable Network Graphics (.png) files.

When taking screen shots that include the command center, use the
Practice database so that the names of the internal machines are not
seen by users.

70 Documentation Department Writing and Style Guide


Formatting
Formatting Voice 2

Formatting screen shots


Images are imported to FrameMaker in anchored frames. Each anchored
frame must be 6.25 inches wide to ensure consistent spacing between the
image and the surrounding paragraphs.

CAUTION
If you need an image from another manual, then copy and paste it to the Images
folder in the your current working folder. Do not import images from any location
other than the Images folder for the manual you are working on. Otherwise, the
location path of the file is tied to the other manual. If that path is broken for any
reason, then your image is grayed out in your working manual.

The following tricks will help when importing and centering different image
sizes:
 For small and medium images, insert a 4.75 inch anchored frame.
Import and center-align your image, and then drag the lower-left corner
of the frame left to 6.25 inches.
 For large images, insert a 6.25 inch anchored frame. Import your image
and align it left at 1.5 inches. Drag the lower-right corner of the image
to the right margin of the page (which makes the image 4.75 inches).

TIP
Always create a right-aligned frame to avoid moving the frame later when
dragging the lower-left edge to the left margin of the page.

Sizing screen Images use Dots Per Inch (DPI) sizing. The DPI at which to import depends
shots on the size/type of image:

Small: Import at 115 DPI and center align.
 Medium: Import at 150 DPI and center align.

Large: Import at 300 DPI, offset from the left at 1.5 inches, and then
drag the lower-right corner of the image to the right margin of the
frame.

NOTE
Always press Shift before dragging an image to ensure the proper ratio when
resizing.

Spacing screen For all images, use the following for spacing:
shots  Top: Offset at .078 inches.

Documentation Department Writing and Style Guide 71


Formatting
2 Formatting Voice


Bottom: Manually adjust the anchored frame so that an 1/8th inch gap
exists between the image and the anchored frame. Create a spacer with
a sticky note to use as a guide. Remember to have the zoom at 100% so
that the marker is accurate to the gap.

Creating cropped Sometimes, screen shots do not show all of the screen. When only a specific
images portion of the screen needs to be shown, use the Snagit Editor to crop the
image, and then, in most cases, add a wavy border.
However, if the relationship of the section to the rest of the screen is not
important, then no indication of the cropping is necessary. For example, a
specific square of a map focused on a feature or an area from a large screen.
To set the wavy border:
1. In the Snagit Editor, select the border tool.
2. Set the edges to use the wave edge option, and then set the
following:
– Effect size: 9
– Apply to: top or bottom, depending on the part of the image being
cropped.

NOTE
On occasion, it might be necessary to apply the wavy border to one of the sides
as well as the top or bottom of the image. For example, when showing the
additional buttons on the toolbar, the bottom and left sides of the image might
need to be wavy.

When cropping with wavy sides, no more than two should be used. Never crop
both the top and bottom, or both the left and right side at one time with wavy
sides.

– Shadow: No shadow
– Outline width: 1 pixel

TIP
Click Add to Quick Styles to save the style. Save a top wave and a bottom wave
style, so that either style can be quickly selected from the Quick Styles area.

3. Click OK to apply the wave edge.

72 Documentation Department Writing and Style Guide


Formatting
Formatting Voice 2

Formatting callouts
Use callouts to point out important fields, areas, or options on the image, or to
add clarification to confusing characteristics. For example, two fields with the
same name on the same screen.
Avoid the overuse of callouts, as they can clutter an image and make it
difficult to understand what is being shown.
In enhancement documents, use callouts to point out appearance changes that
have occurred because of enhancements.
Use initial capitalization in each callout and avoid complete sentences. Apply
the appropriate font attribute to each label.
For spacing, set the Offset From Left field to .125 inches. Set the height and
width to fit the callout label, but no wider than to the edge of the image. Make
sure the section symbol (§) is displayed to use as spacing guide for the callout
arrow. To display the section symbol in FrameMaker, select View > Text
Symbols.
Place the callout arrow from the middle of the section symbol to the middle of
the item being called out. Draw the arrow as close as possible to the item, but
not over the item. Set the line thickness of the arrow to 1 pt. Always use
straight, parallel lines when possible.
If it is not possible to use straight lines—for example, if two screen elements
are so close together that the arrows would overlap if set up in parallel—then
use a line with one bend in it, pointing up to the element. On rare occasions,
bent arrows pointing down to an element might be acceptable.
If a bent line is used, then the line between the bend and the arrow should also
be approximately 1/8th inch tall.
If using clamps (brackets) as the arrow, then the clamp should be
approximately 1/8th inch wide.

TIP
To create straight lines for callout arrows, even with bent arrows, press and hold
Shift before drawing the arrow. For bent arrows, press the Esc key to stop
drawing.

Choose the correct word


The words used in procedures must tell readers exactly what to do. Unclear
direction words cause confusion and frustration. Some design documents or
other sources of information from developers use technical jargon that is
inappropriate in user documentation. Developers can also uses words such as

Documentation Department Writing and Style Guide 73


Formatting
2 Formatting Voice

enter, click, and select interchangeably, even though there are differences in
meaning. It is your responsibility to make sure the correct term is used in
documentation.
Use the following guidelines to select the right word.

Term Definition and usage Example

Active The window or screen the user is currently interacting Use the Task Manager to change the
with. Active windows are displayed in front of active window.
non-active windows.

Address Do not use Utah street addresses as example 123 Main St


addresses. The Utah addressing system (for example,
200 W 300 N) can be confusing to residents of other 3465 Cottonwood Ave
states. Instead, use street addresses with street names.
985 Hwy 52

Add icon Because the buttons to add or remove items are To add multiple entries to a field, click
Remove icon depicted by picture alone, refer to them as the Add or the Add icon.
Remove icon. Doing so helps separate them from
other buttons that might display the text Add or To delete an entry, click the Remove
Remove. In addition, these icons have a restricted icon.
association/usage in the software, usually within
Sentryx screens for a specific area or field.

Alt+underlined letter When referring to an alternate way (on the keyboard) To begin the search, click Accept
on the screen for a user to complete an action. The key to press in (Alt+A).
addition to Alt is often marked on the screen with an
underlined letter in the button name.
Do not use access key.

Appear, appears When something new is added to an open screen. Do When the Out check box is selected,
not use appear when a screen first opens. the Out area appears.

Application parameter The official name for settings in classic Spillman. The following application parameters
Application parameters are stored on the Application must be set for this module to operate:
Parameter table (apparam). SAAs can customize • The adultage parameter must be
their agencies’ Spillman experience through set to 18.
application parameters. • The bookjuve parameter must be
Do not use apparam to mean application parameter. set to Yes.

Available, When an option can be used or selected. Available is The Comm button is available only if
Enabled the preferred term for user documentation, while your agency uses the Commissary
enabled is more appropriate for administration module.
documentation.
Once users are granted Delete
privileges, the Del button is enabled
on all screens privileges have been
granted for.

74 Documentation Department Writing and Style Guide


Formatting
Formatting Voice 2

Term Definition and usage Example

Button When a user clicks that spot on the screen to make an To save the record, click Save.
action occur, such as opening another screen,
performing a search, or saving a record. Buttons have Once a Property Take record is saved,
clear names that are written on them, or have the Post Cash button is available.
commonly understood images, such as the Cut button
Click Use to open the Names screen.
or the Minimize button. Compare to icons.

Cancel When a user stops a procedure or action. Do not use To cancel printing the report, click
quit. Cancel.

Check box When a field is a small box that is marked as selected To print a receipt of the transaction,
with a check mark. Always use check box, not box. select the Print Receipt check box.

Chevron button Standard control to expand or collapse content. Refer From the Inmate List screen, click the
to it as the chevron button, not as an icon or other chevron in the Group By area.
proper name button. Regardless of whether the
chevron is single or double, refer to it as the chevron To expand or collapse the Menu pane,
button. Do not modify the control with a proper click the chevron button.
name, such as the Group By chevron.

Classic When referring to software that uses the older Depending on which module your
(Classic Spillman) architecture, as opposed to the Sentryx architecture. agency uses, see one of the following:
Do not use Old Spillman. • To set up Classic Jail, see “Setting
The Classic architecture works differently in the Up the Classic Jail module” on
background than the Sentryx architecture. It was page 345.
written earlier, so it works more like what the • To set up Jail, see “Setting Up the
Windows 95 and earlier versions did, while the Jail module” on page 450.
Sentryx architecture works more like what the
Windows XP and higher versions do. For more
information, see “Flex” on page 78 and “Sentryx” on
page 81.

Clear When a user removes a check mark from a check box. To not print a receipt for the
transaction, clear the Print Receipt
check box.

Click When a user is to press the left mouse button once. Click OK.
Do not use click on.
Click Search.
Most of the time, a user clicks buttons or options. Use
click rather than choose. Click the Offenses tab.

Close When a user is to remove a screen from the desktop. Close the Names screen.
Do not use quit. Use Close button when referring to
the button that is displayed in the top-right corner of To exit the program, click the Close
the screen and is marked by an X. button.

Code When a user is selecting a value set by the software or In the Transaction field, enter the
an SAA from a Lookup list or drop-down list. Do not code for the type of transaction, or
use valid code because the phrase is redundant. select a code from the Lookup list.
Codes are stored in code tables.
In the Agency field, the code for your
Default code values are listed in prompt font, just like agency is automatically populated.
other specific values.

Documentation Department Writing and Style Guide 75


Formatting
2 Formatting Voice

Term Definition and usage Example

Command line The field on the command center where users can At the command line, enter names to
enter commands to open screens. When directing open the Names screen.
users to perform this action, use the phrase at the
command line. At the CAD command line, enter ac
to open the Add a New Call screen.
In CAD, the command line is also used to enter
commands to speed the process of dispatching (rather To open the Arrest screen, at the
than using the mouse). Additional commands can be command line, enter arrest.
used when CAD is open, so the term CAD command
line can be used to indicate the difference.

Complete When a user is to enter information in multiple fields In the Agency Connection area,
on a screen, or all fields on a screen. complete the following fields:...
Use complete the appropriate fields instead of enter
Complete the form, and then click
information in the following fields.
Submit. For field descriptions, see...

Computer When referring to the machine a user interacts with. When a record is saved, it is saved to
Do not use PC. (It is too informal, though older the server, not your computer, so that
manuals might use it.) Do not use client or terminal, other users can access it.
except in administration documentation.
Do not turn off your computer while
the Billing program is running.

Delete When a user is removing a record from the database. To delete a Name record, click Delete.
Do not use remove or erase.

Detail grid A detail record is connected to record in a main table To add additional MO factors, in the
Detail record and provides more information about some aspect of MO field, click the Detail button to
Detail window that main record. A detail record might contain one open the Modus Operandi detail
piece of information or several pieces of information window.
that are stored in separate fields. For example, in the
Alert Codes field on the Names screen, each alert
code is one detail record.
Detail records are added in detail windows.
Detail grids are used in some parts of the software to
view detail records, instead of opening the detail
window.

Dialog box Interactive, with more than one option to select. Print dialog box
Dialog boxes are dependent on user actions to open or
continue tasks. Typically, tasks in the dialog box must
be completed and the dialog box closed before the
user can continue.

Dock When a user connects one screen to another screen so To dock the List Screen to the Offense
that they act like one big screen, or when a toolbar is screen...
anchored to the edge of the window, as opposed to
floating it within the window or on the desktop.

Double-click When a user is to press the left mouse button twice in In Windows Explorer, double-click
rapid succession. Do not use double-click on. the file name to open the file.

76 Documentation Department Writing and Style Guide


Formatting
Formatting Voice 2

Term Definition and usage Example

Driver license When referring to the document that authorizes a In the DL field, enter the driver license
person to operate a vehicle. Do not use driver’s number.
license or drivers license. Older manuals might not
use this convention, and should be updated
accordingly.

Drop-down arrow, When a user clicks a button to reveal a list of options. In the Offense field, enter the code for
Drop-down list Mostly used the Sentryx architecture. In Classic the offense, or select a code from the
architecture, Lookup button and Lookup list are used drop-down list.
instead. For more information, see “Lookup button”
on page 79.

Email When referring to electronic communications. Enter the email address to which to
Always omit the hyphen, to match the software and forward the message.
common usage. The word message is also acceptable.

Enter When a user must type information in a field and then To open the Application Parameters
press Enter. screen, at the command line, enter
Avoid using type as a verb because is it often used as apparam.
a noun in documentation.

When a user can either type information in a field or In the Agency field, enter the agency
select it from a Lookup list or drop-down list. code or click the Lookup button and
Avoid using type as a verb because is it often used as select a code from the list.
a noun in documentation.
Enter the make of the vehicle in the
Make field.

Exit When a user is completely finished using the To see the changes to the settings, exit
software. Do not use shut down or quit. the software and then restart it.

Field When a user enters information in a specific location In the Offense field, enter the code for
on a screen, which is then stored in a specific place in the offense, or select a code from the
the software. Fields can also be populated by the drop-down list.
software.
When a Name Number is entered in
Fields are often preceded by field labels, which
the Owner field, the Last, First,
explicitly or implicitly provide direction of what
Middle, and DOB fields are
information should be entered in the field. In design
automatically populated with
documents, field labels might be called field prompts,
information from the Name record.
but do not use this term in documentation.
Field names are the label in the schema of the The Time to Serve field is view-only
software for the field. Field names should be and displays how much time an inmate
presented only in administration documentation, and has left to serve on the sentence.
only as needed.
The field name of the Last field on the
Names screen is nmmain.last.

Documentation Department Writing and Style Guide 77


Formatting
2 Formatting Voice

Term Definition and usage Example

Flex The newest branding of the Spillman software. “Flex” The CAD module is available for
refers to the software as a whole, with all of its Spillman Flex.
modules and features. As part of the name change to
Flex, all screens (regardless of architecture) were To open Spillman Flex, click the Flex
given a new color scheme and look. However, the icon on your desktop.
Classic and Sentryx architecture are still used in the
background, and occasionally (mostly in admin
documentation) it might be necessary to make the
distinction using the terms “Classic” and “Sentryx”
For more information, see “Classic” on page 75 and
“Sentryx” on page 81.

From The point at which an action starts. Using this From the screen toolbar, click the Invl
construction helps orient the user to the correct part of button.
a screen when following instructions.

Icon When a user clicks that spot on the screen to make an Click the mapping icon.
action occur, such as opening another screen,
performing a search, or saving a record. Icons have Click the Add icon to add another
pictures without words, and sometimes do not have Name field for the search.
official names. Occasionally, providing an image of
the icon on the first reference is a good idea. Compare
to buttons.

In When something is enclosed or surrounded by On the Names screen, the Name


something else. When fields display information, the record number is displayed in the
information is enclosed in the field. Therefore, in is Number field.
the correct term to use. In the Type field, enter or select the
type of alert.

Introduction When the section introduces readers to what is in the Introduction


chapter. Do not use introduction and overview This chapter provides instructions
interchangeably. Pick one and be consistent about how to start and exit Spillman,
throughout the document. how to open screens, and how to
customize the appearance of Spillman.

Involvement When referring to a link between records. To view all involvements for the
Involvements are labeled by type, such as an Arrest Name record, click the Invl button.
involvement, or a Vehicle involvement. All
involvements for a record can be seen by clicking the When a Vehicle Number is entered in
Invl button or from the Involvements tab. the Related Veh field, a link
(involvement) between the Evidence
In general, use link where possible and put
record and the Vehicle record is
involvement in parentheses.
automatically created.

Key When referring to the things on a keyboard that a user Click OK, or press Enter.
presses to input information. Capitalize the first letter
only. Do not bold or otherwise distinguish keys. Use the Up Arrow and Down Arrow
When talking about the Up Arrow, Down Arrow, Left keys to move through the list.
Arrow, and Right Arrow keys together, use the
generic “arrow keys,” with all lowercase.

78 Documentation Department Writing and Style Guide


Formatting
Formatting Voice 2

Term Definition and usage Example

Link Text that can be clicked to perform an action. Similar To open the StateLink Manager, click
to a button in practice, but visually different. the StateLinkST link, where ST is
Hyperlinks lead to websites. Otherwise, simply use postal code abbreviation for your state.
link.

Log on/Log in The act of accessing the software with a username Log on to the Application Server.
and password. Do not use confuse with the noun term
of logon/login. Generally, log on is the preferred
term. If using log in, use the construction “log in to”
not “log into.”

Lookup button When a user clicks a button to reveal a list of options. In the Make field, enter the make of
Used in the Classic architecture only. The Sentryx the Vehicle or click the Lookup button
architecture uses drop-down lists. For more and select a make from the Lookup
information, see “Drop-down list” on page 77. list.
Never bold Lookup.

Menu Options that expand in the tree-like format, and are From the File menu, select Exit.
used to perform actions. In general, menus are located
at the top of the screen. Do not use pull-down list or To open the Administration Manager,
pull-down menu. select Administration >
Administration Manager.

Message box A small window that opens to provide information to A message box opens, stating that the
users. Normally, the only option in the message box is check was printed.
to click OK.
If your SAA has not set up the
It is preferable to use message rather than error
appropriate setting, then a message
message when possible, and to use message rather
might open, stating the setting that
than message box.
needs to be set up.

Modify In general, use modify rather than change, especially To modify the start date, click the
in headings. Start field, and then....

Navigate When talking about using parts of a screen, use move To see additional entries, use the scroll
around instead of navigate, or use the specific action, bar to scroll through the additional
such as scrolling, panning, or clicking. entries.
Navigate is appropriate when referring to users
The Open dialog box opens. Navigate
moving from folder to folder to find a file.
to the appropriate folder, and then
select the file.

Open When a user is to display a screen. Do not use display To open the Names screen...
a record.

When a users action makes a screen display on the The Property screen opens.
desktop. Do not use access.
Open the Booking screen, and then...

Documentation Department Writing and Style Guide 79


Formatting
2 Formatting Voice

Term Definition and usage Example

Option When a user must select only one of several choices, To use the Offense codes on the map,
normally with a circular marker next to the options. select the Offense Codes option.
Do not use radio button.
If the Do not zoom option is selected,
then when a call is received, the map
does not zoom to the location of the
call.

Overview When the section provides a road map for readers of Overview
what is in the chapter or what tasks need to be To set up the StateLink module, the
accomplished. Do not use overview and introduction following tasks must be completed:
interchangeably. Pick one and be consistent • Set up StateLink users, printers,
throughout the document. terminals, and groups. See X, Y,
and Z sections.
• Set up StateLink settings. See
Section A.

Pane A part of a larger window that functions separately In the CAD pane, the Filter field can
from it, and displays information or buttons used to be used to view only the calls, units, or
interact with another section of the window or devices that match the filter criteria.
application. Different from an area because it
functions more like an expanded menu. The Controls pane can be used to
control the layout of the nodes.

Populates When the software enters information in a field as a When a Name Number is entered in
Automatically response to a user’s action, or without the user doing the Name Number field, the software
populates anything. populates the Last, First, and DOB
Do not use the software and automatically populates fields.
together.
To dispose of the bond, select the
Do not use by default, X is entered. Dispose check box. The Disposed By
and Disposed Date fields are
automatically populated.

Plus sign Standard controls used to expand or collapse content. Expand the Hub Menu item by
Minus sign Refer to them as the plus sign or minus sign, not as clicking the plus sign next to the Hub
icons or other proper name buttons, such as the Menu folder.
Expand or Collapse icon. Do not modify the control
with a proper name, such as the Folder plus sign. To view grouped information, click
the plus sign (+) next to a record.

Press When the software performs an action as soon as a Click OK or press Enter.
user applies pressure to a key or key combination. Do
not use hit. Press Tab to move to the next field.

Record When the user is creating a specific set of information To create a Name record:
that must be saved as a unit, such as a Name record or 1. Open the Names screen...
a Vehicle record.
Avoid using record as a verb. The Name record is linked to the
Vehicle record.

80 Documentation Department Writing and Style Guide


Formatting
Formatting Voice 2

Term Definition and usage Example

Refresh When users perform an action that forces the software To refresh the billing information on
to update information. For the benefit of novice users, the screen, click the Refresh button.
use the phrasing refresh the information on the screen
rather than refresh the screen.

Right-click When a user is to press the right mouse button once. Right-click inside the field and select
Do not use right-click on. Customize from the list.

Search criteria, When a user enters a value or values to narrow a Enter your search criteria, and the
Search set search for information in a database. Use the plural click Submit.
form (criteria, not criterion) even if the user is
searching by only one item of data. To view the search set, click the List
button. A list screen opens and
The set of records yielded by a search is the search
displays the records that match your
set. Avoid using selection set.
search criteria.

Select When a user moves through menu items. Select File > Configure.
For consistency, use select, not choose.

When a user adds a check mark to a check box. Use To show the field, select the Visible
selected instead of highlighted to refer to any option check box.
selected.

Sentryx When referring to software that uses the newer Depending on which module your
(Spillman Sentryx) architecture, as opposed to the Classic architecture. agency uses, see one of the following:
Do not use New Spillman. • For set up for Classic Jail, see
The Sentryx architecture works differently in the “Setting Up the Classic Jail
background than the Classic architecture. It was module” on page 345.
written later, so it works more like what the Windows • For set up for Sentryx Jail, see
XP and later versions do, while the Classic “Setting Up the Sentryx Jail
architecture works more like what the Windows 95 module” on page 450.
and earlier versions did. For more information, see
“Flex” on page 78 and “Classic” on page 75.

Server When referring to the machine that stores an agency’s Once a draft is saved to the server, it
database and that users’ computers connect with to can be accessed from any computer at
exchange information. your agency.

Set up Action used to configure the software, such as setting To use the module, set up the
up the application parameters. Do not confuse with following settings:
the noun/adjective term setup.

Setting When the actions available to a user are determined Depending on the settings established
by a value set by the SAA. by your SAA, the following might
occur...

In administration documentation, the instructions for To not have the software confirm
the software to know what to do or not do when a user StateLink request submission, set the
takes an action. ecreqcon setting to FALSE.

Documentation Department Writing and Style Guide 81


Formatting
2 Formatting Voice

Term Definition and usage Example

Shortcut key When referring to a key, such as F2, that is used to do The Spillman software recognizes
something instead of using the mouse. Most of the many common shortcut keys, such as
time, the term shortcut key is unneeded. Ctrl+C for copying in the text editor.

The following table list common


shortcut keys in Spillman.

Click OK or press Enter.

Shortcut menu When referring to the menu that appears when a Right-click the field, and then select
right-click is performed. List is an acceptable Customize from the shortcut menu.
substitute for shortcut menu. Do not use context
menu.

Spelling checker The tool that helps users correct misspellings. Do not To check the spelling in your
use spell checker. In general, use the wording check comments, click the Spelling Checker
the spelling rather than spell check. button.

Spillman Technical The official name for the Spillman department that CAUTION
Services assists current customers with troubleshooting issues Performing a clean-boot erases
with the software. Before 2015, the department was everything in the memory of the
called Spillman Support. All documentation must be Memor, including the Spillman
updated to reflect the change as manuals are revised. Evidence Scanner program. It is
New manuals use the term Spillman Technical recommended to call Spillman
Services. Technical Services before performing
a clean-boot.

Stopped responding When a program does not respond for a longer time If the software has stopped
than expected. Do not use crash, hang, or freeze. responding, then there could be a
problem connecting to the server.
Contact your SAA.

Summit A name for the software that has been discontinued. To open Spillman Summit, click the
Older manuals might use the term, but as updates are Spillman icon on your desktop.
made, all references to it should be removed.

Tab Some applications group related fields on sections of Use the Charges tab to track the
the screen, rather than in separate windows. Each charges associated with the arrest.
such section is called a tab. Users click tabs to select
them. Click the Inmate tab, and then....

Table Tables store information in the software. Screens are The Names table (nmmain) stores
used to display that information. Name records. Use the Names screen
to view the Name records.

Taskbar In Windows, the long, thin section of at the bottom of In Sentryx, individual screens can be
the screen where open programs are displayed, along minimized without minimizing the
with the date and time. Do not use system tray. command center. To restore a
minimized screen, click its icon on the
taskbar.

82 Documentation Department Writing and Style Guide


Formatting
Formatting Voice 2

Term Definition and usage Example

Text editor A section of the screen or a window where users enter In the text editor, enter the narrative
free text. The area or window contains buttons to for the incident.
format the text. Do not refer to the generic text editor
as any thing other than the text editor. For example,
do not call it the Text Editor area. The text editor is
not given any special formatting.

Toolbars When referring to the long, thin section on a Spillman To add additional information to the
screen where buttons or icons are listed for a user to Name record, from the toolbar, select
perform an action. Most screens have two toolbars: Xname to open the Additional Name
• The main toolbar, which is where the buttons that Information screen.
are common to all Spillman screens, such as Add
From the screen toolbar, click Close
and Search, are located.
Sentence.
• The screen toolbar, which is where the buttons
that are specific to the current screen are located. To open the IBR screen, from the
For example, on the Names screen, the screen toolbar, click the IBR button.
toolbar includes the Invl, Ntwk, and Xname
buttons, while the Non-Custody Booking screen
toolbar includes the Full Book and Fingerprint
buttons.
However, most of the time, the term the toolbar
provides enough orientation.
Users select or click things from toolbars, not on
toolbars.

Tool When referring to a set of features that are used to With the Measure tool, distances can
accomplish a specific task, such as measuring be measured on the map by doing any
distances on the map. When talking about a tool, use of the following:
initial capitalization, but do not give it any other
formatting. The term tool is most often used in To exit the Identify tool, click the
documentation when explaining map elements. Identify button, or press Esc.

Unavailable When an option cannot be used or selected. Before a search is performed on the
Disabled Unavailable is the preferred term for user Names screen, the Add button is
documentation, while disabled is more appropriate unavailable.
for administration documentation.
If your agency does not use the
Do not use grayed out or shaded to mean unavailable.
Commissary module, then the Comm
button is disabled.

Value When information is entered into a field. A field’s If the record’s Date Recov/Rcvd
value can be a name, a color, text, or a number. More value is within the date range specified
appropriate for use in administration documentation. on the Report screen, then...
When referring to specific values, use the prompt font
character tag. By default, the Type field value is
Inv.
In administration documentation, it might be
necessary to stipulate what kind of value is in a field. In the confinedInvlText setting,
For example, an alphanumeric string. Talk with enter an alphanumeric string to set the
developers to confirm the term to use for the value. text displayed for the confined
involvement.

Documentation Department Writing and Style Guide 83


Formatting
2 Formatting Voice

Term Definition and usage Example

Vertical ellipses When referring to the three vertical dots at the end of Click the vertical ellipses, and then
a toolbar that, when clicked, display additional click the Approval button.
buttons that do not fit on the toolbar.
If the Partn button is not displayed on
In older versions of the software, a double arrow was
the toolbar, then click the vertical
used instead of the vertical ellipses. Make sure to
ellipses to display it.
update the references for Flex manuals.

View-only When information in a field cannot be entered or The Historic tab displays the
Display-only modified by a user. View-only and display-only are following view-only fields:....
Read-only synonyms, but to be consistent, pick one and use it
throughout your documentation. The preferred usage Time Left to Serve
is view-only.
Use read-only when referring to files, and use View-only field. Displays the time an
view-only for fields and tabs. inmate has left to serve, based on cal-
culations from the inmate’s Intake and
Always hyphenate the terms, regardless of whether
Release records.
the adjective is used before or after the noun it
modifies.

Wildcard characters Characters that are used to indicate that the software Because it is unclear whether Bob is
is to search for records where any character is used. In the offender’s full name, use the
the software, the wildcard characters are the question following wildcard characters in your
mark (?), the asterisk (*), and brackets ([]). search: ?ob*. This search finds any
Always follow wildcard with the word character. Name records that use one character
For more information, see the RMS User Manual. before the letters o and b and any
number of characters after them. For
example, Robert, Bob, Bobbie, Bobby,
and Roberto.

X Number When referring to a specific record number type, such In the Name field, enter the Name
as Name Number, Booking Number, Incident Number of the suspect.
Number, Offense Number, or Vehicle Number. Older
manuals might not capitalize Number. In the Related Vehicle field, enter the
Vehicle Number of the Vehicle record
to which to link the Evidence record.

ZIP Code Use Microsoft style, which matches the U.S. Postal Once the address is validated, the city,
Service style—all caps on ZIP and an uppercase C in state, and ZIP Code are populated.
Code.

Zoom level How many times the zoom has been increased or 10x zoom
decreased. Mostly used when talking about maps or
images. When talking about zoom level, use a
lowercase x with no other formatting to indicate the
zoom level.

Use explicit if-then statements


In casual conversation and writing, the word then is often dropped from
if-then statements, such as “If you go, I’ll go too.”

84 Documentation Department Writing and Style Guide


Formatting
Formatting Voice 2

As part of being accurate and professional, Spillman documentation always


includes the then so that all if-then statements are explicit. However, each
sentence should have only one then in it for clarity, even if it is not an if-then
statement. The following table lists examples of incorrect constructions using
then, and their corrected counterparts.

Incorrect Correct

If a required field is not completed, the record cannot be If a required field is not completed, then the record cannot
saved. be saved.

To format a tab, right-click the tab, and then select Tab To format a tab, right-click the tab, select Tab Style, and
Style, and then select the type of tab style to apply. then select the type of tab style to apply.

If more than one MO factor exists, then enter information If more than one MO factor exists, then enter information
about the first factor, and then click Detail to add about the first factor. Click Detail to add additional factors.
additional factors.

Use coordinating conjunctions correctly


Use a comma and a coordinating conjunction to connect two independent
clauses. For example, “Select the agency for which the call was dispatched,
and then press Enter.” Do not use a semicolon to connect two independent
clauses.
The following words are coordinating conjunctions:
 and  nor
 but  so
 for  yet
 or

The following words are not coordinating conjunctions:



although 
then
 however  therefore

Do not use a comma and one of these words to join independent clauses. The
sentence would be a run-on sentence containing a comma splice.

Eliminate run-on sentences


Use a period between declarative sentences. Be careful not to join sentences
incorrectly with a comma or other punctuation mark. For Spillman style, do
not use a semicolon to connect two independent clauses.

Documentation Department Writing and Style Guide 85


Formatting
2 Formatting Voice

Even if your sentence is grammatically correct, it could be a “run-on”


sentence because the sentence is long and running on. Consider breaking a
long sentence into two sentences at a natural pause in the sentence. The
following table shows an example of a grammatically correct sentence that
works better as several sentences.

Running on sentence Naturally separated sentences

To attach an existing Booking record, which is already To attach an existing Booking record, which is already
linked to the Inmate record, to the Offense record, click linked to the Inmate record, to the Offense record, click
Attach Record to open the Add Bookings to Current Attach Record. The Add Bookings to Current Record
Record screen, select the desired Booking record, and then screen opens. Select the desired Booking record, and then
click Add Selected. click Add Selected.

Use verbs correctly


An expression cannot be a sentence without a verb.
As explained in Chapter 1, most technical writing is done in present tense
with simple verbs. In technical writing, varying voice or mood for the sake of
variety is not appropriate. Put the action of the sentence in the verbs, not in an
infinitive phrase.
Be aware of your use of transitive and intransitive verbs. Unlike intransitive
verbs, transitive verbs must have an object to which to transfer the action of
the subject. The following transitive verbs are sometimes wrongly used as
intransitive verbs:
 authenticate  install

complete 
populate
 configure  print

display 
process

Never use the following construction: The screen displays. Use The screen is
displayed, or the preferred, The screen opens.

86 Documentation Department Writing and Style Guide


Formatting
Formatting Bulleted Lists 2

Formatting Bulleted Lists


Use a bulleted list when a series of ideas, options, or items does not have a
appear in a particular order. Also use bulleted lists when providing an
overview of the following sections.
When making a bulleted list, follow these guidelines:
 Use an initial capital on the first word in each bulleted item.
 If the bulleted item is a complete sentence, then end it with a period. If
the bulleted item is not a complete sentence, then do not end it with a
period.
 Do not mix complete and incomplete sentences in a bulleted list.
 Use a colon to introduce a bulleted list.
 Use run-in headings in bulleted lists as appropriate.
 Use the bu-bullet paragraph tag to create bulleted lists. If an item in
the list has subpoints, then use the bs-Bullet-Sub paragraph tag. If
an item in the list needs a second paragraph, then use the
b2-Bulletp2 paragraph tag.
 Use the A-No Lines table format for a bullet list with paragraph
bodies, when space and aesthetics require it. Use the bs-Bullet tag
for paragraph format. This table is often used for bullet lists with
f-field prompt bodies, when options are listed, but not fully
described. Use the bs-Bullet-Sub tag for options described within
the field prompt.

NOTE
For information on bulleted lists in tables, see “Formatting table paragraphs” on
page 117.

Documentation Department Writing and Style Guide 87


Formatting
2 Formatting Capitalization

Formatting Capitalization
Use the following guidelines to correctly capitalize elements of your
documentation:

Application parameters and settings. In general, use all lowercase
when you refer to an application parameter or setting. However, if the
setting uses camel case (likeThisDoes), then copy how it is written in
the software. Avoid using the parameter or setting name as the first
word of a sentence or heading.

Incorrect Correct

the GBCROSS parameter the gbcross parameter


the BOOKJUV setting the bookJuv setting

NOTE
UNIX is case sensitive, so the correct capitalization of UNIX commands and
application parameters must be documented. Check with the developer of your
project to make sure the correct format for UNIX commands and application
parameters is documented.


Bulleted items. Capitalize the first word of each bulleted item.

Incorrect Correct

From a menu, the following tasks can be From a menu, the following tasks can be
performed: performed:
• select a program, table, or report • Select a program, table, or report
• select a submenu to go to another report • Select a submenu to go to another report
• enter a command to exit the menu or the • Enter a command to exit the menu or the
software software


Button names. Capitalize button names in the documentation exactly
as they appear in the software. However, always capitalize OK
regardless of how it appears on the button. Use OK only if it appears as
a button in a dialog box or a message box. If a button uses an image or
symbol rather than words, use title capitalization for the button name.
For example, the Move Up button.

Company names and products. Capitalize company names and
products from other companies as they are found on the companies’
websites. If the website cannot be located, confirm the correct
capitalization of the company name with the PLM or BA. For example,
ADSi (Application Data Systems, Incorporated), ArcView (Esri,

88 Documentation Department Writing and Style Guide


Formatting
Formatting Capitalization 2

Environmental Systems Research Institute, Inc.), and ProQA (Medical


Priority Consultants, Inc.)
 Data to be entered. Capitalize data and commands to enter exactly as
they should be entered. Do not capitalize y or n if the letter does not
have to be capitalized upon entry.
 Department names. Capitalize department names similar to the
following: Spillman Technical Services, or the Training department.
Notice that the name of the department has title capitalization, but that
department is not capitalized.
 Environment variables. Use all caps when referring to an
environment variable. For example, the SPOOLER environment
variable.
 Field labels and other elements. Most field labels appear in the
software with title capitalization that should be duplicated in the
manual. For example, the Alias For field on the Names screen
(names), the Application Parameter Value field on the Application
Parameters screen (apparam), and the How Received field on the Law
Incident screen (law).
Capitalize record names, table names, report names, and screen names
similarly. Note that none of these elements receive any other
formatting.

Correct

the System Maintenance menu

a Law Incident record

the Individual Arrest report

the Additional Name Information screen

 File names. When using file names in documentation, match name


conventions and capitalization to what is in the software.
 Heading 1s and chapter titles. In chapter titles (paragraph tag
cna-Chapname) and Heading 1s (paragraph tag h1-Heading 1) use

Documentation Department Writing and Style Guide 89


Formatting
2 Formatting Capitalization

initial caps on all but unimportant words. Lowercase prepositions of


four or fewer letters, such as “with.”

Correct

Module Setup and Maintenance

Using Environment Variables

Repairing the Active Calls and Unit Status Tables

Assigning User Logins and Setting Up Groups

Setting World Security

Guidelines for Security

Defining Security for an Involvements Screen


Heading 2s, Heading 3s, and block titles. In any headings below the
first level, capitalize the first letter of the first word and any proper
nouns as appropriate.

Correct

Turning on agency partitioning

Adding a Law Incident record

Giving a CAD user additional access

Giving records managers access to the table’s Partn option

 Keys. When referring to a key on the keyboard or a function key, use


initial capitalization. Older manuals use all caps, and references to keys
should be updated as the manual is updated.

Correct

Press the Spacebar.

Click Accept (Alt+A).

Press Enter to close the message box.

90 Documentation Department Writing and Style Guide


Formatting
Formatting Capitalization 2
 Manuals. Capitalize manual titles and references to books as shown in
the following examples.

Correct

the General Tutorial

the CAD User Manual

the Spillman Application Setup and Maintenance Manual

your computer user’s guide

your network administration guide

 Menu names. Use initial capitalization for the menu name, but do not
capitalize the word menu unless referring to the Tree Menu. When
instructing users to select a menu, use initial capitalization for the entire
name of the menu, including the word menu, and bold the name.

Correct

the Tree Menu

the Main menu

the Names Table Reports menu

Select the Vehicle Table Reports Menu from the Hub menu.

 Messages. Capitalize messages exactly as they appear on the screen, or


show a screen capture.

Correct

“DRIVE” is preferred over “Dr”; use it (Y/N)?

Documentation Department Writing and Style Guide 91


Formatting
2 Formatting Capitalization


Modules and interfaces. Capitalize only the name of the module or
interface. If an interface or module uses abnormal capitalization, then
keep the capitalization, as shown in the following examples.

Correct

the Geobase module

the Computer-Aided Dispatch module

the DEx interface

the ProQA interface


Modes. Capitalize only the first letter of the mode. For example, Add
mode or Modify mode. Do not give modes any other formatting. Older
manuals might use courier font or bold for modes, and should be
updated.
 Privileges. Capitalize the first letter of specific privileges. For
example, Access privileges or Modify privileges. Do not capitalize
privileges, and always use the plural form.
 Program names. Show program names in all lowercase because users
enter them at the command line in all lowercase.

Correct

sypriv

apparam

gbstreet


References to steps or columns. When referring to a step number or a
column, use lowercase.

Correct

5. Repeat step 4 as needed.

Use the values in the Total column as a guide.

92 Documentation Department Writing and Style Guide


Formatting
Formatting Capitalization 2
 Table text. Use initial capitalization of each item in a table.

Press To

Ctrl+X Accept a record.

Enter Close the message box.

Ctrl+T Enter the current date and time in the field.

Documentation Department Writing and Style Guide 93


Formatting
2 Formatting Commands, Files, and Menu Items

Formatting Commands, Files, and Menu


Items
Consistently formatting command, files, and menu items helps users
recognize these important elements in the documentation.

Formatting commands
Commands tell the software to execute an action using parameters. Command
formats show users how to enter the parameters for the command.
When documenting command formats, enclose optional parameters in braces
({}). Required parameters can be written without braces or enclosed in
brackets ([]). In most CAD commands, the pipe symbol (|) means or.
Information in normal style must be entered exactly as shown, while
information in italics is variable information the user supplies. Hyphenate
compound variables. For example, requesting-unit#.
Remind users that they should not type the braces, brackets, or other special
markings when entering command. The following is a sample command
format using the DQ command from CAD:
dq [requesting-unit#] [last,first {m}] {mmddyy}
{sex}{st}{.comments}

Formatting files and file extensions


Use the prompt font character tag to set off file names from the surrounding
text. For example, “Open the StateLinkCA.war file.”
Use the same conventions for directory names as for file names.
As a general rule, on the first reference, use the file type (PDF, text, JPEG)
and the file extension (.pdf, .txt, .jpg). After that, refer only to the file type.
For example, “The CAD User Manual is available as a PDF (.pdf) on the
Knowledgebase. The CAD Tutorial is available as a PDF as well.”
Avoid using specific file types when possible. For example, instead of using a
WAV file, write an audio file, or instead of a JPEG file, write an image file.
The Geobase and GeoValidation documentation is an exception. Sometimes,
the file types are not known, so using the file extension is appropriate.
When referring to a particular file extension, show the extension in lowercase,
preceded by a period. For example, “Bitmap files have the .bmp extension.”

94 Documentation Department Writing and Style Guide


Formatting
Formatting Commands, Files, and Menu Items 2

When referring to files in general by their extension types, use uppercase and
do not precede the extension with a period. For example, “Use RoboHelp to
create CHM files.”

Formatting menu items


When telling users to select a menu item, including items in the Tree Menu,
use bold type for the items, and greater-than symbols between items. Do not
bold the greater-than symbols. Space around the greater-than symbols. For
example, Screens > Law Enforcement > Law Incident.
When referring to a menu without telling users to select it, do not use bold
type. For example, “The Reports menu is used to access the reports associated
with the Jail module.”
Do not call menu items commands, as this creates too much confusion with
the commands used at the command line.

Documentation Department Writing and Style Guide 95


Formatting
2 Formatting Cross-References

Formatting Cross-References
Cross-references are powerful tools to connect parts of a document or two
documents together. Cross-references help readers find additional information
quickly, and remove the need for rewriting information. Use cross-references
whenever practical to improve the way information is presented to readers.
When documenting tasks that use universal elements of the software, such as
the Application Server or text editor, do not explain in detail how to access or
use those elements of the software. Instead, provide a cross-reference to the
manual in which the element is described in detail.
Cross-references are introduced in the following ways:

In paragraphs, use “For more information, see cross-reference.”

In bullet list items, use “See cross-reference.”

Creating When providing a cross-reference to another section in the same manual, the
cross-references cross-reference should be created using FrameMaker’s Cross-Reference
within a manual feature. FrameMaker automatically updates the cross-references when the
book for the manual is updated, and automatically creates a hyperlink to the
reference in the PDF version. This feature also makes updating references
easier.
To create a cross-reference:
1. Open the FrameMaker Cross-Reference dialog box.
2. In the Source area, complete the following fields:
– Document: Select the document to which to create the
cross-reference. To create a cross-reference to the current
document, select Current.
– Source Type: Select Paragraphs.
The paragraph markers are displayed in the Marker Types list, and
the paragraphs that use the marker are displayed in the Paragraphs
list.
3. Select the paragraph marker of the cross-referenced information, and
then select the paragraph from the list.
4. In the Reference area, in the Format field, select the Heading &
page format. (Note the lowercase on page.) Occasionally, using the
page # format might be appropriate.

The word see is never part of the inserted cross-reference.


5. Click Insert.
The cross-reference is created and displayed in blue.

96 Documentation Department Writing and Style Guide


Formatting
Formatting Cross-References 2

Creating When providing a cross-reference to another document, the cross-reference


cross-references must be entered manually because FrameMaker cannot generate
to another manual cross-references between books.
Reference only the document, not any chapter or section names, nor any
chapter or page numbers. All of these elements can change as manuals are
updated. Readers should be able to use the table of contents in the referenced
document to find the information being referenced.
Remember to use italics if the reference is to an official manual. For example,
the RMS User Manual. If a generic reference to a manual is used, then do not
use italics. For example, the StateLink manual has multiple versions and
might be referred to in generic terms.

Creating a Each chapter of a manual contains a mini-TOC, which is created using


mini-TOC using cross-references to each Heading 1 in the chapter.
cross-references
Creating the cross-references in the mini-TOC is the nearly the same as
creating other cross-references. However, in the Format field, select the
Chapter Mini TOC format.

Understanding the lack of indexes


Nearly all manuals use cross-references instead of indexes for the following
reasons:
 FrameMaker inserts cross-references in the table of contents so the
TOC often acts as enough of an index.

FrameMaker inserts hyperlinks for all cross-references when a PDF is
created, so readers do not need to use an index to look up page numbers
for topics.
 Most readers use electronic versions of manuals with the hyperlinks,
instead of printed versions, where an index would be needed.

Most manuals are short enough that an index would not add anything to
the reader experience.
 The creation and maintenance of indexes are long and time-consuming
processes.

Documentation Department Writing and Style Guide 97


Formatting
2 Formatting Field Descriptions

Formatting Field Descriptions


Use field descriptions to provide lists of fields and what information should
be entered in the fields. In procedures, use the following format to refer to
field descriptions:
6. Complete the appropriate fields. For field descriptions, see “Fields
on the Example screen” on page 98.
When making a field description list, use a block title to mark the start of the
field descriptions, as shown in the following example.

Fields on the When introducing field descriptions, use one of the following constructions:
Example screen  The Example screen contains the following fields.
 The following lists fields on the Example screen.

Field label

Use the f-field prompt paragraph tag for the field name.

Example check box

Use the pd-promptdesc paragraph tag for the description. FrameMaker


automatically selects the paragraph tag after the f-field prompt tag. The
pd-promptdesc tag is basically the same as the b-body tag.

Another field

If needed, field descriptions can use the A-No Lines table format for a bullet
list with paragraph bodies, when space and aesthetics require it, especially
when options are listed, but not fully described.

– Option A – Option B
– Option C – Option D

Use the bs-Bullet-Sub tag for options described within the field prompt.

98 Documentation Department Writing and Style Guide


Formatting
Formatting Fonts 2

Formatting Fonts
Changes in font type are signals for readers that the information in the
different font is important. Use font types consistently to help users locate
important information. For callouts, use the same font types as in other text.
The following table lists the fonts styles used for manuals.

Font style Used for Example

bold Area names In the Narrative area, select the Narrative record.

Button names, except the Lookup Click the Validate button.


button. Click the Lookup button to select a code.

Check boxes Select the Arrested? check box.

Field names In the Address field, enter the person’s address.

Folder names that are proper folder Open the AddData folder.
names. Navigate to your installation folder.

Icon names that are proper icon Click the Add icon.
names. The mapping icon is displayed.

Link names To return to the Names Search screen, click the


Return to Search link.

Run-in headings Gender neutral terminology. Use dispatcher,


not she.

Search options The search types are Equal, Not Equal,


Between, Less Than, Greater Than, Sounds
Like, Contains, Blank, and Not Blank.

Tabs Select the Arrests tab.

bold Courier Examples to enter (‘such as’ only) Enter the first name of the person, such as 
font George.
(input font)
Specific info to enter At the command line, enter lwmain.

Documentation Department Writing and Style Guide 99


Formatting
2 Formatting Fonts

Font style Used for Example

Courier font Command formats To run a driver license query, use the command
(prompt font) format DQ [requesting-unit#]
[last,first {m} ] {mmddyy} {sex}
{st} {.comments}.

Examples to enter (‘for example’ Enter the first name of the person. For example, 
only) George.

File names (for specified proper file Open the options.xml file.


names only) Save the document as an XML file (.xml).

Formats (used for all formats that are Enter the sever path using the following format: 
not date- or time-based) http://hostname:port/, where hostname
is the name of your server.

Location/directory paths Navigate to the /sds/Users directory.


Save your file to the following location:
/sds/World/Group/Users/

Message text or text that the screen A dialog box opens with the following message:
displays Save a copy?

Parameter and setting names, and Set the invlrshp application parameter to 
privilege names (Actual privileges True.
themselves, for example, Add, For users to access the Mobile Field Report, the
Modify, or Access, are in regular mdcmdFRIncident privilege must be granted.
font.)

Specific values 1/Yes/True, 0/No/False

Table names (Note that the table name Open the Names screen (nmmain).
comes after the screen name in
parentheses.)

Table record names Codes are saved in the apagncy table.

Tags (For specified proper tag names Copy the <TimeOut> tag.


only.) Copy the date and time tags.

italics Variable information (Usually related Enter the date in the mm/dd/yyyy format.
to number formatting, such as date, Enter the time in the hh:mm:ss format.
time, phone number, or versions.) Enter the phone number in the (xxx) xxx-xxxx
format.
Enter the sever path using the following format: 
http://hostname:port/, where hostname
is the name of your server.

Emphasis (Use sparingly.) Do not shut off your computer while saving.

100 Documentation Department Writing and Style Guide


Formatting
Formatting Headings 2

Formatting Headings
Heading are sign posts readers use to know where to look for information.
Headings also break topics into clear, manageable chunks of information.
Headings should be concise, but include enough information to accurately
describe the text that follows.
Use the following guidelines when formatting headings:
 Make sure each heading, by itself, provides sufficient information.
For example, even if a Heading 1 is Adding Records, a Heading 2 that
says By duplicating is not a good heading. The Heading 2 should read
Adding records by duplicating.
 Word headings consistently, using active verbs. Introductions and
overviews are exceptions.
 Do not stack headings. Each heading must have an introduction or
other text following it. Make sure that the heading reflects all material
in the section—and only that material.
 As a general rule, at least two subordinate headings of the same
level should be in a section. For example, a Heading 1 should be
followed by two Heading 2s, not a Heading 2 and a Heading 3.
However, exceptions are possible.
 Headings are not acceptable antecedents for pronouns. The first
sentence after the heading often repeats what is in the heading, which is
a good way to reassure readers that the information in the section is
what they are looking for.
 In general, Headings do not have punctuation, and should never
have ending punctuation. Proper names for screens and modules are
capitalized as they are officially named. Heading font supersedes any
other font rule. For example, do not use prompt or input font in any
heading (including block titles).
The following table shows examples of each type of heading used in manuals.

Heading format Notes

A Heading 1 (H1) is used to introduce a main topic in a chapter, such as a screen or


Heading 1 a concept. Use the h1-heading 1 paragraph tag for all H1s. Make sure all H1s
use initial capitalization for all words, except for articles and other small words. The
following lists H1 examples:
• Searching for Records
• Adding Offense Records
• Working with Involvements
• Validating and Submitting eFR Forms

Documentation Department Writing and Style Guide 101


Formatting
2 Formatting Headings

Heading format Notes

Heading 2 A Heading 2 (H2) is used to break up an H1 topic into a smaller subtopics. Use the
h2-heading 2 paragraph tag for all H2s. Make sure all H2s use initial
capitalization for the first word, and then all lowercase words, except proper nouns.
The following lists H2 examples:
• Performing an advanced search
• Using the tabs on the Offense screen
• Using system-created involvements
• Adding a saved signature using eSign
Heading 3 A Heading 3 (H3) is used to break up an H2 subtopic into even smaller subtopics.
Use the h3-Heading 3 paragraph tag for all H3s. Make sure all H3s use initial
capitalization for the first word, and then all lowercase words, except proper nouns.
The following lists H3 examples:
• Using the advanced date search
• Using the Arrest tab on the Offense screen
• Understanding the warn function
• Saving an eSign document in another location
Block title Block titles are more versatile than regular headings, and are not restricted to going
heading underneath H3s. For example, if information within an H1 section is complex, but
should not be broken up in to subheadings, then block titles can be used. Block titles
visually break up information without separating it. Block titles are not included in
the TOC. Block titles work well for example scenarios and field description lists.
Use the bt-blocktitle paragraph tag for all block titles. Make sure all block
titles use initial capitalization for the first word, and then all lowercase words,
except proper nouns. The following lists block titles examples:
• Fields on the Arrest screen
• On the server
• Example scenario using Keep Separate records
• Fields on the Name tab on the eFR form
Run-in heading. Body text. Lore Run-in headings are useful for highlighting information in a bulleted list or body
ipsum dolor sit amet vestibulum. text. A run-in heading is created by bolding the first sentence, phrase, or word of a
paragraph, and adding a period after the heading. The period should also be bold.
The following bulleted list is an example of using run-in headings.
FrameMaker follows different rules for each type of heading:
• H1. Always start at the top of a new page.
• H2. Do not start a new page, though their larger gaps can cause them move to
another page sooner. H2s also move to keep with the following body paragraph.
• H3. Behave much the same way as H2s, though they have a smaller gap between
paragraphs, so they jump to the next page later.
• Block title. Are left-aligned on the page. There is a larger gap between block
titles and the preceding body paragraph than between two body paragraphs. The
next body paragraph after a block title lines up with it.
• Run-in heading. Run-in headings are treated like the surrounding text, such as a
bulleted list or body paragraph.

102 Documentation Department Writing and Style Guide


Formatting
Formatting Line and Page Breaks 2

Formatting Line and Page Breaks


Avoid breaking a line in the middle of a path or other technical information.
Use Shift+Enter to force a soft line break in Word and FrameMaker
documents.

Incorrect Correct

If the offense is Drug/Narcotic, then the If the offense is Drug/Narcotic, then


property type cannot be 11 = Drug/Narcotic property type cannot be
Equipment. 11 = Drug/Narcotic Equipment.

Line breaks in If a path or other information could cause an awkward line break, then enter
Help the path on its own line or use non-breaking spaces to keep information
together.

Line breaks in When updating or proofing indexes, make sure that main entries are not
indexes placed at the bottom of a column. Use the Keep with Next option in
FrameMaker to move main entries to the top of the next column.

NOTE
Currently, the Documentation department does not create indexes for manuals.

Page breaks Occasionally, whole paragraphs will need to be forced to the top of the next
page to fix a bad page break. For example, if a line ends with a colon, such as
an introduction to a procedure, and the information following the colon starts
at the top of the next page, then the lines need to be kept together.
Page breaks can be fudged by changing the number of widow/orphan lines for
a single paragraph. Normally, this technique is neither necessary nor
recommended. However, it can work when tables need to be forced to a
different page.

TIP
Slightly changing the size of a graphics frame is another way to fix a bad page
break.

Do not use the Special > Page Break option. It fixes the page break
temporarily, but invariably results in more bad page breaks when later
changes cause text to shift.

Documentation Department Writing and Style Guide 103


Formatting
2 Formatting Line and Page Breaks

To force a paragraph from the bottom of a page to the top of the next page in
FrameMaker:
1. Place your cursor in the paragraph to move.
2. Select Format > Paragraph > Designer.
The Paragraph Designer dialog box opens.
3. In the Keep With area of the Pagination tab, select Nxt Pgf.
4. Click Apply.

104 Documentation Department Writing and Style Guide


Formatting
Formatting Numbered Lists and Procedures 2

Formatting Numbered Lists and


Procedures
Use a procedure whenever presenting sequential tasks, regardless of whether
the tasks are performed by the software or a user. When a procedure or task
needs to be completed using a series of steps in a specific order, use a
numbered list to mark each step.
Use the following guidelines when documenting procedures:
 Do not use a number list for procedures that have only one step.
Use a bullet or write the procedure into the paragraph.
 Most procedures should be less than seven steps and should not be
more than 10 steps. If a procedure has many steps involved, then look
for ways to combine steps into sub-steps or for other ways to present
the information, such as field descriptions or tables.
 Consider including two actions in a single step, but do not include
more than two actions in one step. For example, “Click the Arrest
tab, and then select the offender.” Also consider omitting obvious
actions such as “Click OK.”
 Keep procedures generic, but include examples where necessary.
Often, a step can be clarified just by adding an example, such as a
sample data item. Use screen shots for clarification as well. For more
information, see “Use screen shots” on page 70.
 Always document the preferred method of doing something. Use a
table to document alternative methods for performing a task.
 Make sure to often orient readers during procedures. For example,
From the toolbar, click the Add button rather than Click the Add
button. Orient first, rather than at the end of the step. For example, use
At the command line, enter names, rather than Enter names at the
command line.
However, be judicious in orienting—orientation is not needed at every
step. When actions in a procedure are optional, explain the result or
reason before describing the action. When actions must be completed,
the action can be described first.
– If the action is imperative to complete the procedure, then use
phrasing similar to the following: Click Print to open the Print
dialog box.
– If the action is optional in the procedure, then use phrasing similar to
the following: To mark the event as a medical event, select the
Medical Event check box.

Documentation Department Writing and Style Guide 105


Formatting
2 Formatting Numbered Lists and Procedures


When finished with a procedure, do not insert more body text. It
can be confusing whether the body text is actually part of the
procedure. Also, do not hide body text after a table or image, including
in procedures.

Restrict procedures to one item only. For example, adding a record
instead of adding records. However, if the other headings in a section
are plural, then the heading for a procedure can be plural also.

Do not start procedures immediately following a heading. Always
include an introduction paragraph or sentence.

Start each step with a user action.

Correct

Adding records to the Property screen

To add a record to the Property screen:


1. Open the Property screen.
2. Click Add.
3. In the Item field, enter the name of the item.

The following procedure is an example of a correctly formatted numbered list.


To make a numbered list for a procedure:
1. Select the lb-ListBegin paragraph tag, and then write the first
step.
The software formats the step with the number one.
2. Select the l2-Listp2 paragraph tag, and then write the result of the
first step.
The software formats the result without a number.
3. Select the l-List paragraph tag, and then do any of the following:
– Continue to write each step and result, alternating with the
l-List and l2-Listp2 paragraph tags.
– If needed, use the ls-List-Sub and ls2--list sub2
paragraph tag to add substeps and reactions under a step.
– If needed, use the ls-List Sub-Sub and ls2s-list sub 2
sub paragraph tag to add subsubsteps and reactions.

106 Documentation Department Writing and Style Guide


Formatting
Formatting Punctuation 2

Formatting Punctuation
This section describes how to use and format punctuation marks. Refer to the
Chicago Manual of Style for punctuation style issues not addressed in this
section.
Avoid using double punctuation.

Formatting punctuation marks


If a punctuation mark is not part of the displayed text or text to be entered,
then format it with the character format appropriate for the paragraph format
in use. For example, “Enter Flutie, Adam, and then click Accept.”
Notice that the first comma (between Flutie and Adam) is text that is entered,
so it has the formatting for input, while the second comma (after Adam) is to
connect the two independent clauses, so it has standard body text formatting.
Also notice that the period at the end of the sentence is not bold because the
period is part of the body text, but not part of the button name.
Another example of correctly formatted punctuation is “The following
message opens: No matching records were found. Do you want to
add a new record?”
Notice that the question mark is part of the displayed text, so it has prompt
text formatting.
When parentheses are used, apply the character formatting of the text outside
of the parentheses to them. Do not use the character formatting of the text
inside the parentheses. For example, “Define agency partitioning in the User
Privileges table (sypriv).”
On rare occasions, a punctuation mark might be used in a heading. In this
case, the punctuation mark should be formatted to match the rest of the
heading.

Documentation Department Writing and Style Guide 107


Formatting
2 Formatting Punctuation

Using colons
The following table lists correct uses of colons.

Correct Example

To introduce a bulleted list. Generally, complete the When a warning flag is added to an involvement, the following
clause that precedes the colon. occurs:
• The involvement is moved to the top of the list.
• A red exclamation point (!) is added to the involvement.
• The involvement is displayed in red.
To introduce a list in a sentence. Spillman has the following types of date and time fields: a date
Insert only one character space between the colon and field, a time field, and a time/date field.
the first item. Capitalize the first word that follows the
colon only if that word is a proper noun or if the text
that follows the colon forms a complete sentence.

To introduce a procedure. To open an involvement from the Names screen:


1. At the command line, enter names.
The Names screen opens.
2. Search for the desired record....

To introduce displayed text in a separate paragraph. The following prompt appears in the lower-left corner of the
screen:
Search complete. 0 results found.

To introduce a large amount of displayed text in a The following message appears: Please search for an
sentence. existing record before adding a new record
If the displayed text is short, then do not use a colon. to this table.
The screen displays THEFT 08/03/2005 (ACTIVE).

To introduce a format for user-entered text in a Use the following format for all radio log entries:
separate paragraph. unitcode ten-code comments

NOTE
Following a colon, write the following in a new paragraph:

– Isolated text
– Large amounts of displayed text
– Formats the user should use

108 Documentation Department Writing and Style Guide


Formatting
Formatting Punctuation 2

Because it can be easy to misuse colons, the following table lists incorrect
uses of colons.

Incorrect Comment

To introduce a series of headings. Do not treat headings as if they were bulleted text. Use a period
to introduce a series of headings, such as a group of Block Title
headings.

At the end of a table heading. Table headings do not use any punctuation. For more
information about formatting tables, see “Formatting Tables”
on page 116.

To introduce a table or an image. Use a period to introduce both images and tables. For an
example, see the introduction to this table. For more
information, see “Using periods” on page 113.

To introduce information users enter in the software. The difference in font is enough to signal where the entered text
begins. For example, “In the Last field, enter Johnson.” For
more information, see “Formatting Fonts” on page 99.

Using commas
The following table lists correct uses of commas.

Correct Example

To separate independent clauses joined by a coordinating Click Accept, or press Alt+A.


conjunction.
Select the agency from which the call was dispatched, and
For more information about coordinating conjunctions, see
then press Enter.
“Use coordinating conjunctions correctly” on page 85.

To separate the last two items in a series (the serial or If privileges have been granted, then users can add, modify,
Oxford comma). delete, and partition records on the table.

To set off an introductory phrase, regardless of length. Next, open the Names screen.
If the introductory clause is followed by two independent
On the CAD menu, select New Unit Status Window.
clauses, then use a comma after only the introductory
clause. When Accept is clicked, the software adds the record and
On the rare occasion that an introductory clause contains the Involvements screen closes.
parentheses, drop the comma to avoid using double
punctuation.

To set off the parentheses symbols. In Spillman documentation, parentheses, (), indicate that
the information is for clarification.

To separate long numbers. For more information, see “Use In 2015, Spillman served 1,400 agencies in 41 states, and
numbers correctly” on page 34. nearly 70,000 public safety professionals.

Documentation Department Writing and Style Guide 109


Formatting
2 Formatting Punctuation

Because commas can be overused, the following table lists incorrect uses of
commas.

Incorrect Comment

To join independent clauses (comma splice). Use a coordinating conjunction with the comma, or make
the independent clauses separate sentences.

Anywhere is there a natural pause in the sentence. Just because readers would pause in the sentence at a certain
point, it does not always mean a comma belongs there.
Think about the structure of the sentence, and not just how it
will be read.

To separate a dependent clause from an independent It is tempting to use the comma incorrectly in these cases
clause when the independent clause comes first. because when the order is reversed, the comma should be
used. Avoid this temptation.

To separate items in a series, all of which have Because it is confusing which commas are pairs setting off
non-essential information included. For example: the non-essential clauses and which commas are part of the
“Spillman has three types of date and time fields: a data series, semicolons should be used in place of the series
field, in which you enter the date, a time field, in which commas, as in the following example:
you enter the time, and a time/date field, in which you “Spillman has three types of date and time fields: a date
enter both the time and the date.” field, in which you enter the date; a time field, in which you
enter the time; and a time/date field, in which you enter both
the time and the date.”
NOTE: Even with the comma problem corrected, this is
still a terrible, unnecessary sentence construction that
should not be used in Spillman documentation. The
information would be better presented in a bulleted list.

Using ellipses
Rarely is there is a need to use an ellipsis (...) in technical writing.
If commands, screen names, or other items in the software contain ellipses,
then do not document the ellipses. For example if the screen name is
displayed as “Print...” then document the screen name as “Print.”
Do not use an ellipsis following a table heading.
On the rare occasion when an ellipsis should be used, type three periods in a
row. Do not space between the periods. If, on an extremely rare occasion, an
ellipsis needs to be used at the end of a sentence, then type four periods in a
row—three for the ellipsis and one to end the sentence.

110 Documentation Department Writing and Style Guide


Formatting
Formatting Punctuation 2

Using em dashes
Use an em dash (—) to create a long pause in a sentence. Do not leave any
space on either side of the em dash. Do not over use the em dash. For
example:
“To protect records with a password, a user must be able to run the
appropriate program—for example, the Law Incident program if the user is
protecting law records—and be able to access the Pwd option from the option
line in that program.”
To make an em dash, do one of the following:
 In FrameMaker, press Ctrl+Q, and then Shift+Q.
 Press Alt+0151 (on the numeric keypad). This method works in
FrameMaker, Word, and RoboHelp.

Using en dashes
Use an en dash (–) to indicate a range of numbers, to indicate a negative
number, and in certain compound adjectives. (Refer to the Chicago Manual of
Style for examples of compound adjectives that require an en dash.)

NOTE
In the Spillman software, no distinction is made between a hyphen and an en
dash. Therefore, do not tell readers that they must make an en dash to add a
negative number.

Do not use a hyphen (-) instead of an en dash.


Do not use the words from and to when indicating a range of values. Instead,
use the format in the range of x–y.
The following are examples of the correct use of en dashes:
 Repeat steps 5–7.
 For example, enter –15 to remove 15 hours from the inmate’s sentence.
 Enter a value in the range 2–5.
To make an en dash, do one of the following:

In FrameMaker, press Ctrl+Q, and then Shift+P.
 Press Alt+0150 (on the numeric keypad). This method works in
FrameMaker, Word, and RoboHelp.

Documentation Department Writing and Style Guide 111


Formatting
2 Formatting Punctuation

Using exclamation points and semicolons


Do not use exclamation points (!). Rarely does a circumstance in technical
writing warrant an exclamation point.
The software uses exclamation points as symbols. In these cases, document
the exclamation point as a symbol.
Do not use semicolons (;). Rarely does a circumstance in technical writing
warrant a semicolon.
Keep sentences short and simple by using a period or a coordinating
conjunction, instead of a semicolon, between independent clauses.

Using hyphens
Use a hyphen (-) to make compound adjectives, such as view-only. The
following examples of compound adjectives are common to Spillman
software and documentation:
 Computer-Aided Dispatch  right-click
 display-only field, view-only field  system-defined involvements

double-click 
ten-code
 highest-priority offense  user-configurable settings
 incident-based reporting  x-coordinate

on-call scheduling 
y-coordinate

NOTE
When referring to the x-coordinate and the y-coordinate together, the following
construction is acceptable: “The x- and y-coordinates are displayed.”

For other compound adjectives, follow the guidelines in the Chicago Manual
of Style.
Use a hyphen to distinguish between words that sound the same but have
different meanings. For example, recreate (as pertaining to recreation) and
re-create (to create again), or recover (to feel better after an illness) and
re-cover (to cover again). For more information, see the Chicago Manual of
Style.
Do not hyphenate the word email, to match the software.
For the words x-coordinate and y-coordinate, do not break a line after the
hyphen.

112 Documentation Department Writing and Style Guide


Formatting
Formatting Punctuation 2

Using parentheses
Double-check that your parentheses are in pairs. A missing parenthesis is a
sign of sloppy work or lazy reviewing. Avoid using parentheses to create a
parenthetical plural. For example, complete the following task(s). Instead, use
the plural form, and trust that readers will understand that in some instances
the plural does not apply.
The following table lists correct uses of parentheses.

Correct Example

To enclose table names. Open the Names screen (nmmain).

To enclose icon/button/symbol images. (Use sparingly.) Click the mapping icon ( ).

To enclose pertinent or conditional information. Complete the following tasks:


– Create the appropriate records.
– Create IBR records (only if your agency uses the IBR
module).
– Transfer records to the copied database.
To enclose references in rare instances. ...if offenses other than the highest-priority offense contain
Most of the time, references are created with the an action code that is valid for return B2 (see the following
FrameMaker Cross-Reference feature and are not list) and the action code falls in the same class as the
enclosed in parentheses. Also, do not enclose references highest-priority offense.
such as The following table lists this in parentheses.

Using periods
Use the Smart Spaces option to make sure your documentation has only one
space following a period.
To make sure the Smart Spaces option is selected, do the following:
1. In FrameMaker, select Format > Document > Text Options.
The Options dialog box opens.
2. Select the Smart Spaces option.
3. Click Apply.

Documentation Department Writing and Style Guide 113


Formatting
2 Formatting Punctuation

The following table lists correct uses of periods.

Correct Example

After items in a bulleted list that are complete sentences. The GeoValidation and Response Plans modules are
If items in a bulleted list are not complete sentences, then designed to work with CAD. These modules improve
do not use a period. dispatching by doing the following:
Do not mix complete and incomplete sentences in a • The GeoValidation add-on module stores detailed
bulleted list. For more information, see “Formatting address information for your area, validates addresses
Bulleted Lists” on page 87. as they are entered, and check for warnings or alerts
associated with addresses.
• The Response Plans add-on module allows your agency
to predefine how your agency will respond to incident
occurring at specific addresses.

This section describes the following information:


• Involvements
• Warnings
• Alerts
After run-in headings, including in a bulleted list. Bold the The Menu screen contains the following elements:
period as part of the run-in heading. For more information, • Close button. This is the standard Close button. Click
see “Formatting Headings” on page 101. this button to exit the screen.
• Title bar. This bar displays the name and version of the
software.
• Command line. This is where commands are entered to
tell the software to open other screens or run other
programs.

At the end of a declarative or imperative sentences, Right: If the software is not working as explained, then the
including in tables and field descriptions. Response Plans module is probably not yet working. Ask
Avoid other punctuation marks, such as exclamation points your SAA when to start using Response Plans.
(!) or semicolons (;). Wrong: If the software is not working as explained, then
Avoid long sentences and comma splices. For more the Response Plans module is probably not yet working,
information, see “Eliminate run-on sentences” on page 85. ask your SAA when to start using Response Plans.
Not Spillman style: If the software is not working as
explained, then the Response Plans module is probably not
yet working; ask your SAA when to start using Response
Plans.

At the end of an introduction to a table or image. For more The following table lists buttons on the Names screen.
information, see “Formatting Tables” on page 116 and The Names screen opens.
“Use screen shots” on page 70.

When referring to a particular file extension, precede the Bitmap files have the .bmp extension.
file extension with a period.

114 Documentation Department Writing and Style Guide


Formatting
Formatting Punctuation 2

Using quotation marks


Do not use quotation marks to enclose text information such as displayed text,
text users are to enter, keys, text that defines an environment variable,
buttons, and so on. Instead, use the appropriate font formatting. For more
information, see “Formatting Fonts” on page 99.
Design documents might use quotation marks where official Spillman
documentation would not. It is your responsibility to remove the quotation
marks as the information is transferred to documentation.
Use the Smart Quotes option to make sure your documentation uses serif
quotation marks (“b”) rather than sans serif quotation marks ("b").
To make sure the Smart Quotes option is selected, do the following:
1. In FrameMaker, select Format > Document > Text Options.
The Options dialog box opens.
2. Select the Smart Quotes option.
3. Click Apply.
Occasionally, it might be necessary to show quotation marks around a blank
space. To make sure the quotation marks are the proper quotation marks (“b”
rather than “ “) enter the letter b in place of the blank space, and then change
the color of the character to white. FrameMaker reads the hidden character as
quoted text and formats the quotation marks correctly.
Always place periods and commas inside quotation marks. Always place
colons outside quotation marks. Question marks and semicolons depend on
whether the punctuation is part of the quoted material. If a question mark or a
semicolon is part of the quoted material, then place it inside the quotation
marks. If it is not, then place it outside the quotation marks. For example,
What is the definition of “politically correct”?
On the very rare occasion when it is necessary to use quotation marks inside
another set of quotation marks, use the double quotation marks for the most
outside set of quotation marks, then use single quotation marks for the inner
set of quotation marks. For example, she asked, “What is the definition of
‘politically correct’?”

Documentation Department Writing and Style Guide 115


Formatting
2 Formatting Tables

Formatting Tables
Use tables to add clarity and to help organize information. Tables are useful in
the following situations:

Discussing several things with the same categories of details

Condensing paragraphs that are too long or bulky

Listing facts

Repeating groups of items

Comparing multiple items

Selecting a table Use the following guidelines to select a table format:


format 
Use the C-Lines table format to explain correlated data.
 Use the ABu-No Lines Bullet table format for a bulleted list with
paragraph bodies, when space and aesthetics require it.

Creating a table Use the following guidelines when creating tables:


 Introduce a table with a complete sentence and a period. Do not use
a colon to introduce a table. (Some older manuals might use colons
still, and should be revised.)
 In table headings, capitalize the first word and proper nouns. In
table text, capitalize the first word of a column and proper nouns.
 Do not use punctuation following a table heading. In table text, use
periods following complete sentences.
 Use parallel wording in table headings and in table text. Use
parallel wording in all the headings in one table and all the text in one
table. Be as consistent as possible throughout the entire document.
 Left-justify table headings and table text. Vertically center-align
table headings.

When needed, use a note in a specific cell to clarify information.
Make the word note all uppercase and bold, as shown in the following
table.

System privilege Description Privilege

HyperlinkManager Gives users the ability to add and modify Access, Add, Modify
hyperlinks on the map.
To add and modify hyperlinks, Access, NOTE: This privilege should be given to
Add, and Modify privileges are required. administrative users only.

116 Documentation Department Writing and Style Guide


Formatting
Formatting Tables 2

Sizing tables
Use the following guidelines when formatting tables.

Table width If the table appears between paragraphs of body text, then make the table 4.75
inches wide, then same width of the paragraph text. However, if needed, a
table can be as wide as 6.25 inches, which is the width of the page.

Column width When possible, use consistent column widths on all tables on the same page.
However, adjust the width of columns as needed for readability and aesthetic
quality.

Table alignment If the width of a table is 6.25 inches, then left-align the table. Otherwise,
center-align tables.

Formatting table paragraphs


Apply the th-tablehead paragraph tag to headings in tables.
In table text, use the appropriate paragraph tag.

Paragraph tags for tables

For body text in a table, use tt-tabletext.


• For first-level bulleted text, use tb-table bullet.
For a second-level paragraph in a bulleted list, use tb2-table bullet 2.
1. For the first step in a procedure, use tlb-table list begin.
2. For subsequent steps, use tl-table list.
For a second-level paragraph in a step, use tl2-table list 2.
– For a bullet within a procedure, use tls-table list sub.

In table text, use the appropriate character tag:


 For text that the user enters, use Input as-is. “As-is” refers to the
size of the text. Normal table text is 9 pts. Input as-is and Prompt
as-is change the font but retain the current size (9 pts).

For text that the screen displays, use Prompt as-is.

To make selected table text bold, right-click and select Style > Bold
(Ctrl+B).

To make selected table text italic, right-click and select Style > Italic
(Ctrl+I).

Documentation Department Writing and Style Guide 117


Formatting
2 Formatting Tables

The following is a correct example of a table.

To Do this

Open the Names screen (nmmain) At the command line, enter names.

Formatting tables for settings and privileges


The following formats are guidelines when documenting application
parameters, module and system settings, and system privileges within tables.
Tables with different row designs are options to use when the information
needs flexibility. However, keep the format consistent throughout a table—do
not use two formats within one table. Describing information can vary, so the
table used to present the data will reflect the table’s introduction.

Application When describing application parameters, use the following column heading,
parameters and one of the following row designs.

Parameter Description Value

adprhist Add Property History Yes

Creates a Property History record for each modification to the Property record. Sentryx IBR
uses these records in cases where one Property record is tied to multiple incidents or arrests.

allowTempTelWithBonds True/False

Allows Temporary Release with Bonds


Determines whether a user can temporarily release an inmate without clearing bonds.
• Set to True to not require a user to clear bonds before releasing an inmate temporarily.
• Set to False to require a user to clear bonds before releasing an inmate temporarily.

118 Documentation Department Writing and Style Guide


Formatting
Formatting Tables 2

Module and When describing module or system settings, use the following column
system settings heading, and one of the following row designs.

Setting Description Value

allowTempRelWithBonds Determines whether a user can temporarily release True/False


an inmate without clearing bonds.
• Set to True to not require a user to clear bonds
before releasing an inmate temporarily.
• Set to False to require a user to clear bonds
before releasing an inmate temporarily.

allowTempRelWithBonds True/False

Allows Temporary Release With Bonds


Determines whether a user can temporarily release an inmate without clearing bonds.
• Set to True to not require a user to clear bonds before releasing an inmate
temporarily.
• Set to False to require a user to clear bonds before releasing an inmate
temporarily.

Documentation Department Writing and Style Guide 119


Formatting
2 Formatting Tables

System privileges When describing system privileges, use one of the following formats:
 Required privileges. When describing privileges that are required for
the module, use the following format.
The following table lists the Spillman tables for which users will need
access and the required privileges.

Table Description Privilege

apagncy Used to open the Agency Codes screen. Add, Modify


Conditional privileges. When describing privileges that are
conditional for the module, use the following format.
The following table lists the system privileges for the Mobile Field
Report module.

System privilege Description Privilege

mdcmdlFRIncident Gives users access to the Mobile Field Add, Modify


Report module.

Add and Modify privileges are


recommended for most users.

fieldmanager Gives users access to the Field Manager Access


screen.
NOTE: Users with Access privileges are
Access privileges are needed to use the able to modify field labels, hide fields,
screen, but the screen is not needed for most and make fields required.
users.

editallnarrs Gives users access to modify or delete Modify, Delete


narratives authored by another user. This
privilege affects system-wide settings in NOTE: This system privilege is not
Mobile, and is not recommended for most recommended for most users.
users.

120 Documentation Department Writing and Style Guide


Formatting
Formatting Tables 2

Using “blank” as a value in a table


For parameters or settings whose value should be blank, or if an option to use
is to leave the field blank, use (blank).

Parameter Description Default value

ecmobscr Send Through Mobile All/(blank)


Sends the StateLink transaction forms through Mobile.
• For StateLink 2.0, the value should be set to All, and should not be
modified.
• For StateLink 1.0, leave the value blank, or enter which transaction
forms should be sent to Mobile.
For more information, contact Spillman Technical Services.

ecpasfmt State Password Format #,#/(blank)


Defines the minimum and maximum number of characters required for a
state password, and automatically enables the state password feature when
values are set.
To set the state password format, enter the minimum and maximum values
required by your state, separated by a comma. For example, if the required
length is between 4 and 8 characters, then enter 4,8. If the value is left
blank, then the state password feature is disabled.

Occasionally, a situation where a cell in a table should be left blank can occur.
The decision of how to present that blank cell is context-based.
For example, in the IBR manual, the Crime Against column lists the entity
against which the crime was performed, but some of the incident reports for
IBR, such as Justifiable Homicide, are not crimes. In this case, leaving the
column blank does not make sense and using the value Not a Crime is the
better solution.
In the Mobile Admin manual, the Module column lists the modules the
privileges are applicable to, and there are some privileges that are not
applicable to any module. In this case, using (none) is a better solution than
leaving the cell blank.

Using notes, tips, and cautions


All Note, Tip, and Caution boxes are tables. Notes, tips, and cautions are used
to draw attention to important information of which readers must be aware.
Use notes, tips, and cautions sparingly. Try not to have more than two on a
two-page spread.

Documentation Department Writing and Style Guide 121


Formatting
2 Formatting Tables

Instead of using notes, try to reorganize the information. If there are more
than two notes on a page, then try to combine them into one note with two
paragraphs. However, if doing so hides the second part of the information,
then two notes is probably the better way to present the information.
Avoid stacking notes, tips, or cautions, and avoid using them immediately
following a heading.
Notes, tips, and cautions should appear as in the following examples.

NOTE
Notes call attention to information that is of particular importance or that varies
depending on a particular condition, such as the way the Spillman Application
Administrator has configured the software. Keep notes short. Do not overuse
them, or they will lose impact. If your note is too lengthy or contains a number of
steps, then consider putting the information under its own block title.

TIP
Tips present recommendations, optional actions, and additional ways to perform
specific tasks. These should be of real value to a large number of users and
verified by the Development, Technical Services, or Training department.

CAUTION
Cautions point out actions that might endanger the users’ data or its integrity
(usefulness) or cause other problems later. Place cautions appropriately. Do not
wait until the end of a procedure to put in the caution note.

To insert a Note, Tip, or Caution box:


1. In FrameMaker, select Table > Insert Table.
The Insert Table dialog box opens.
2. In the Table Format area, select A-Caution Table, A-Note table,
or A-Tip table, depending on the type of table to add.
3. Click inside the box and enter NOTE, TIP, or CAUTION. Apply the
th-tablehead paragraph tag to the text.

4. Press Enter, and then enter your text for the note, tip, or caution.
Apply the n-Note paragraph tag to the text. Use the prompt-as is
character tag when including text that appears on the screen in a
note, tip, or caution. Use the input-as is character tag when
including text that the user enters in a screen.

122 Documentation Department Writing and Style Guide


Formatting
Formatting Tables 2

5. If multiple paragraphs are needed, then use Shift+Enter to create a


line break. Doing so maintains the correct spacing between the
paragraphs.

NOTE
On rare occasions, a note, tip, or caution might need to include a bulleted list or
steps.

To make a bulleted list, perform a hard return (just Enter, rather than Shift+Enter),
and then use the bs-Bullet-sub paragraph tag with the call out character
tag.

To make a numbered list, perform a hard return, and then apply the
nb-NotesBegin paragraph tag. For subsequent steps, apply the ns-Notes
paragraph tag. For reactions to steps, use Shift+Enter before and after the
reaction.

Carefully consider the reasons for having steps in a note. If the information is
complex enough to need steps, it might be better explained in its own section,
rather than in a note.

Documentation Department Writing and Style Guide 123


Formatting
2 Formatting Tables

124 Documentation Department Writing and Style Guide


Chapter 3

Responsibilities

Jump to topic:
Introduction 126
Improve the Product 127
Label Documentation Correctly 128
Using Copyedit Checklists 129
Responsibilities
3 Introduction

Introduction
This chapter explains some of the responsibilities of the Spillman
Documentation department, and includes the following:

“Improve the Product” on page 127

“Label Documentation Correctly” on page 128

“Using Copyedit Checklists” on page 129

126 Documentation Department Writing and Style Guide


Responsibilities
Improve the Product 3

Improve the Product


Even though technical writers rarely interact with customers, writers should
be the users’ advocates and look for ways to improve the product.
Inform your development teams of any of the following problems:
 Inconsistencies in the way the software works or looks, such as how
fields are grouped together.
 Unfriendliness in the software, such as a large number of steps to
complete a simple task.

Messages, especially error messages, that are unclear, inaccurate, or
poorly worded.
 Spelling mistakes in every part of the software. Be sure to include the
correct spelling, instead of simply stating the word is misspelled.
 Inconsistencies in capitalization, including in field names, button
names, and error messages. Check the capitalization of OK, ToolTip,
and StateLink, especially.
If a potential problem or inconsistency is found in the software, then first
check the Requirements Specification document (RSD) to see if the software
is behaving as planned.
If the software is not behaving as planned, then make sure your client and
server are set up correctly. If needed, talk to a developer or trainer for help. If
your client and the server are set up correctly and the problem persists, then
talk to your development team, and submit a bug.
If the software is behaving as planned, then talk to the Product Line Manager
(PLM) about your suggested change. The PLM might provide more
information about why the software must behave the way it is, or they might
incorporate the change. Always use email, not word of mouth, so that you
have a history of the bug report.
All spelling and capitalization issues should be reported as bugs, no matter
how small.
Submitting a bug is no guarantee that the problem or inconsistency will be
fixed quickly or fixed at all. The Development department will analyze the
bug based on how badly it affects functionality, how many customers see and
use the feature, and how much time it would take to fix.
If the bug is not fixed immediately, then determine if the feature needs to be
documented. If it does need to be documented, then document the feature as
directed by the PLM and the Documentation department manager.
Sometimes, it will be appropriate to document the feature as it currently
works, and sometimes it will be appropriate to document the feature as it
should work.

Documentation Department Writing and Style Guide 127


Responsibilities
3 Label Documentation Correctly

Label Documentation Correctly


Part of creating documentation is naming the documentation itself, as well as
the files and images used to create the documentation, and the folders that
store the files and images. Consistent, concise labeling of files, images, and
folders helps your fellow writers know what is going on if and when
responsibilities for manuals change. Consistent, concise labeling of
documentation helps readers find the document in all the storage locations.
Use the following guidelines for labeling documentation elements correctly:

Keep names short, and simple.

Do not use spaces.

Use an underscore (_) to separate words.
 Do not use punctuation marks or other symbols. Some programs cannot
read them or might interpret them as something else.

128 Documentation Department Writing and Style Guide


Responsibilities
Using Copyedit Checklists 3

Using Copyedit Checklists


Use the following checklists as copyedits are performed. When requesting
copyedits, make sure to tell the editor what level edit they should perform.
Focus on format and Spillman style when editing. Do not get caught up in the
differences between your style and the other writer’s style.
When giving comments, try to reference the page number in the style guide
(or other source) that applies to the edit. Doing so helps to validate the
comment and helps all writers become familiar with the style guide.
The following are tips to use when editing, including self-editing:
 Check the headings in the TOC and mini-TOCs. It is a great way to
catch changes, missed formats, or double listings, and to make sure the
organization makes sense.
 Check cross-references to catch changes to headings.
 Use analytical thinking to fine-tune your editing radar. In conjunction
with department formats and styles, analyzing the writing will help to
catch logical fallacies and information gaps.
For example, suppose a set of instructions says click something, and
then select something, but there are no reaction descriptions in
between. A discrepancy exists between what the user is doing, from
where they are doing it, and what happens after they do it.
From our formatting and styles, the terms click and select are specific
to the location and association of that action. Therefore, they are not
interchangeable, and we can assume the orientation and reaction for
each must be different. We can then ask more comprehensive questions
of how, what, where, when, and why that are related to the instructions
or information given. For example, if a user selects an item, then it is
probably from a menu. If there is a menu, then from where is it
accessed? At what point was it opened?
Such logical progression is helpful and necessary when editing for
unfamiliar or inaccessible software. It also gives the writer a red flag to
re-evaluate what they are trying to describe.
The following resource might help to better understand and develop
analytical thinking:
http://www.visualthinkingmagic.com/framework/competencies/analyti
cal-think.

Documentation Department Writing and Style Guide 129


Responsibilities
3 Using Copyedit Checklists

Light Copyedit Checklist (Basic)



Checked the removal of 'you’
 Checked grammar, spelling, punctuation

Checked capitalization and hyphenation

Checked font formats: bold, prompt, input, italics

Checked heading formats

Checked step formats and introductions

Checked bullet list formats and introductions
 Checked table formats and introductions

Checked note box formats

Checked image format and spacing
 Checked call out format and spacing
 Checked cross-references

Checked page numbering and manual title
 Checked manual cover and copyright page
 Checked preface and versioning

Checked manual TOC and chapter mini-TOC

Medium Copyedit Checklist (Intermediate)


5 Cs = Clear, Correct, Concise, Complete, and Consistent

Completed Light copyedit

Checked gender neutrality
 Checked terminology and word usage

Checked writing point of view and tense usage

Checked logic and clarity of content
 Checked sequential information

Checked for information gaps

Checked for consistency and redundancy

130 Documentation Department Writing and Style Guide


Responsibilities
Using Copyedit Checklists 3

Heavy Copyedit Checklist (Advanced)


5 Ws and 1 H = Who, Where, What, When, Why, and How

Completed Light copyedit
 Completed Medium copyedit
 Checked for organizational weakness
 Checked for weak syntax and lack of focus
 Checked for vague generalizations
 Checked for wordiness, triteness

Checked for smooth transitions and flow
 Checked for balanced paragraphs
 Checked writing style and tone

Documentation Department Writing and Style Guide 131


Responsibilities
3 Using Copyedit Checklists

132 Documentation Department Writing and Style Guide


Appendix A
The tables in this appendix provide information that might be helpful to
members of the Documentation department.

Using function keys


In the software, users can press function keys to perform common tasks.
The following table describes each function key.

This Has this Ctrl key


Press the function key to
function key combination

Accept Alt+A or Ctrl+X • Begin a search after you enter search data.
• Save your changes after adding or modifying a record.
• Return to the toolbar after adding or modifying a record.
• Select a highlighted item (for example, in a Lookup window or a list). In
most cases, pressing Enter also selects a highlighted item.

Backspace Ctrl+H Erase the character to the left of the cursor.

Begin Ctrl+A • Go to the beginning of the current field or line.


• Go to the first record in the search set (after performing a search).
• Go to the first record in a table (if the cursor rests at the toolbar and no
search set is active).
• Go to the first item in a list.
Cancel Alt+C or Ctrl+C • Cancel the modification of a record without saving your changes (if the
cursor rests at a field with the screen in Modify mode). The software
saves changes to detail field entries.
• Cancel the addition of a record (if the screen is in Add mode).
• Close the current screen (if the toolbar is visible).
• Close a Lookup window without selecting an item.
• Stop a search.

Clear Ctrl+Z • Clear the search set (after performing a search).


• Clear all fields in the current record (if no search set is active).
• Clear the current field of data.
Delete Ctrl+D Erase the character to the right of or under the cursor (depending on the
keyboard).

Detail Ctrl+N Open a detail window.

Documentation Department Writing and Style Guide 133


A

This Has this Ctrl key


Press the function key to
function key combination

Down Arrow (none) • Go to the next field in the record.


• Go to the next record in the search set or table.
Editor Ctrl+E Open the text editor.

End Ctrl+G • Go to the end of the current line or field.


• Go to the last record in the search set or the table (if the toolbar is visible).
Enter Ctrl+J • Cancel the entry in the current field.
• Select the highlighted item.
• Return to the toolbar (if the cursor is at the last field in a record).
Eol Ctrl+K Clear the current line or field, from the cursor position to the end of the line.

GoTo Ctrl+O Number the fields so that a field can be selected to modify.

Help Ctrl+W Display a menu of help options.

Home Ctrl+^ • Go to the first field of the current record.


• In CAD, go to the next status window (New Calls, Dispatched Calls, or
Unit Status) on the CAD status screen.

Insert Ctrl+R Switch between the Ins and Ovr key-in modes.

Left Arrow (none) Move the cursor to the left.

Lookup Ctrl+E • Display a Lookup window listing the codes that are valid for the current
field (if the field is coded).
• Select an outline and/or enter the text editor to enter data in a comments
field.
• Search for a record to use in a Name block.
• Display a list of available programs (if the cursor is at the command line).
Mail Ctrl+Y Read or send mail.

Next Ctrl+N • Go to the next page in a list or code table.


• Display a list of the search types available for the current field.
• Open a detail window.
Prev Ctrl+P • Go to the previous page in a list or code table.
• Copy the just-used search data to the record being added.
• Clear all search data.
Print Alt+P Print a record or a report.

Recall Ctrl+U • Undo changes just made in the current field. The software restores the
value that previously existed in that field.
• Copy information from the corresponding field in the most recently dis-
played record to the current field in the displayed record.

Redraw Ctrl+L Repaint the screen to remove any irregularities.

134 Documentation Department Writing and Style Guide


A

This Has this Ctrl key


Press the function key to
function key combination

Right Arrow (none) Move the cursor to the right.

Run Ctrl+V Run another program and then return to the current program.

Tab Ctrl+I Move to next section of a mapped value, such as a Social Security Number
or a date. For example, press Tab to move from the month portion of the date
to the day portion.

Time Ctrl+T Enter the current date and time in a date-time field.

Type Ctrl+N Display a list of possible search types (Ignore, Equal to, Not equal to,
Between, Less than, and Greater than).

Up Arrow (none) • Go to the previous field in the record.


• Go to the previous record in the search set or table.

Understanding computer terms


When writing about the software and interacting with the Development teams,
the following term definitions might be helpful. This list is not exhaustive.
Use the Internet to find definitions of other computer terms that are
unfamiliar.

Term Definition

AIX A UNIX operating system created by IBM. Use the phrase AIX operating system as opposed to just
AIX in documentation.

CDPD Abbreviation for Cellular Digital Packet Data.

client The computer or application on a computer that communicates with the server.

CTPERL A programming language.

daemon In UNIX, a process that runs in the background and performs a specified operation at predefined
times or in response to certain events. Daemons can be controlled with scripts, such as Dstat,
Dstart, and Dstop.

database An organized collection of searchable data from which users or computers retrieve information.

DSL Abbreviation for Digital Subscriber Line.

FTP Abbreviation for file transfer protocol. Even though developers might, do not use FTP as a verb, or
to mean file transfer.

GIS Abbreviation for Geographic Information System.

HTTP Abbreviation for Hypertext Transfer Protocol.

ISDN Abbreviation for Integrated Services Digital Network.

Documentation Writing and Style Guide 135


A

Term Definition

ISP Abbreviation for Internet Service Provider. Do not use ISP provider.

Java A programming language.

LAN Abbreviation for Local Area Network.

local, personal Local refers to settings that are specific to a particular computer, while personal refers to settings
that are specific to a particular user, and are tied to the user’s login name.

NFS Abbreviation for Network File System.

ODBC Abbreviation for Open Database Connectivity.

Perl A programming language.

PI Abbreviation for protocol interface.

query A transaction that seeks information from a database, but does not change information.

SMTP Abbreviation for simply mail transfer protocol. Used to transfer email.

SQL Abbreviation for Structured Query Language. A computer language used to ask questions about
data in a relational database.

TCP/IP Abbreviation for Transmission Control Protocol/Internet Protocol. The basic communication
language or protocol of the Internet.

UNIX An operating system for computers. Many agencies use a UNIX server rather than a Windows
server. When referring to UNIX, use all caps, as shown.

VGA Abbreviation for video graphics array.

Web As in the World Wide Web. In nearly all cases, capitalize Web. For example, Web browser, Web
address, Web page. However, website is correct.

Understanding law enforcement terms


When writing about the software and interacting with the Development teams,
the following term definitions might be helpful. This list is not exhaustive.
Use the Internet to find definitions of other law enforcement terms that are
unfamiliar.

Term Definition

AFIS Abbreviation of Automated Fingerprint Identification System. An AFIS can be a local or state
system.

ALERT Acronym for America’s Law Enforcement Retiree Team. A free consultation service on missing
children cases for law enforcement agencies.

136 Documentation Department Writing and Style Guide


A

Term Definition

ALI In E9-1-1 software, an abbreviation of Automatic Location Identification. It displays the address
information of the subscriber who is calling 911. The information includes the address, community,
state, type of service, and (if appropriate) business name. Often talked about with ANI information,
and called ANI/ALI information. Pronounced “Annie/Alley.”

ANI In E9-1-1 software, an abbreviation of Automatic Number Identification. It displays the number of
the subscriber who is calling 911. Often talked about with ALI information, and called ANI/ALI
information. Pronounced “Annie/Alley.”

CAD Abbreviation of Computer-Aided Dispatch. Use all uppercase unless cad is a part of a command
that users enter in lowercase letters. Also, make sure CAD appears in all uppercase in the software.

CJIS Abbreviation for Criminal Justice Information Services. Pronounced “SEE-jis.” CJIS is a division
of the FBI, and is responsible for providing law enforcement agencies with sensitive information
about citizens to fight crime while also protecting civil liberties. Agencies must adhere to CJIS
policies to protect information. State-level CJIS divisions also exist, such as Arizona’s ACJIS.

docket A formal abridged record of the proceedings in a legal action, or a register of such records. A list of
the legal causes to be tried.

DOJ Abbreviation of Department of Justice.

EMS Abbreviation of Emergency Medical Service.

IBR Abbreviation of Incident-Based Reporting. IBR is a national program run by the FBI to collect data
on crime information. IBR information is given to the National Incident-Based Reporting System,
or NBIRS. Each state collects the information slightly differently, so each state also has its own
IBR program, such as SCIBRS (South Carolina Incident-Based Reporting System), or TXIBRS
(Texas Incident-Based Reporting System).
A similar program from fire incidents also exists, and is called the National Fire Incident Reporting
System, or NFIRS.

MPS, MUPS Abbreviation for Missing Persons System, and Missing and Unidentified Persons System,
respectively.

NCIC Abbreviation for National Crime Information Center. A project of the FBI that helps agencies
share information about criminals and crimes at a national level.

NCMEC Abbreviation for National Center for Missing and Exploited Children.

NIST Abbreviation for National Institute of Standards and Technology. NIST is a non-regulatory federal
agency within the Commerce Department’s Technology Administration. The agency works with
industry to develop and apply technology, measurements, and standards.

NLETS Abbreviation for National Law Enforcement Telecommunications System. NLETS is a system for
law enforcement agencies to share information with each other. States can also have their own
systems. For example, the California Law Enforcement Telecommunications System is called
CLETS.

serve To bring to notice, deliver, or execute as required by law. To make legal service upon a person
named in a process.

shell When talking about ammunition, shell is used to refer to shotgun ammunition, but not to refer to
rifle or handgun ammunition.

Documentation Writing and Style Guide 137


A

Term Definition

state, state database When referring to policies made by a state. For example, “The state might required users to send a
password when querying the state database.” Do not capitalized the word state.

subpoena As a noun, a writ commanding a person designated in it to appear in court under a penalty for
failure. As a verb, to serve or summon with a writ or subpoena.

summons A warning or citation to appear in court. A person might be summoned to appear on a particular
day to answer to the plaintiff or to appear as a witness.

UCR Abbreviation for Uniform Crime Reporting. The umbrella term for NIBRS and other reporting
methods for the FBI. UCR is a nationwide statistical effort to gather data on crimes.

VIN Abbreviation for Vehicle Identification Number, which is the number that uniquely identifies each
vehicle that is manufactured. Do not use VIN number.

want, warrant A document that authorizes an officer to make an arrest, a seizure, or a search, or to do other acts
incident to the administration of justice. Use warrant to mean both wants and warrants.

Using proofreader marks


The following are proofreader marks used when copy editing a physical copy
of a manual.

Symbol Meaning Example

delete

close up

delete and close up

caret

insert a space

space evenly

let stand

transpose
used to separate two or more
marks and often as a concluding
stroke at the end of an insertion

138 Documentation Department Writing and Style Guide


A

set farther to the left

set farther to the right


set as ligature (such as)
align horizontally

align vertically
broken character
indent or insert em quad space
begin a new paragraph

spell out

set in CAPITALS

set in SMALL CAPITALS

set in lowercase
set in italic
set in roman

set in boldface

hyphen multi-colored

en dash 1965–72

em (or long) dash Now—at last!—we know.

superscript or superior

subscript or inferior

centered

comma

Documentation Writing and Style Guide 139


A

apostrophe
period

semicolon

colon

quotation marks

parentheses

brackets
query to author: has this been
set as intended?
push down a work-up

turn over an inverted letter

wrong font
1The last three symbols are unlikely to be needed in marking proofs of photocomposed 

matter.

Using style sheets


Use a style sheet to keep track of format/style in the document for consis-
tency. Include any oddities specific to your manual. For example, “inci-
dent-based” vs. “incident based.”

Style Sheet
ABC DEF
Acronyms are spelled out on first‐time use “describe” vs “discuss”
“Complete the fields” vs “Enter information” “displayed” vs “displays” 
“click” vs “click on” “driver license” 
“Enter” vs “Type” information
“From” toolbars/menus

140 Documentation Department Writing and Style Guide


A

GHI JKL
“in” vs “on” tables/screens “log in” vs “login”
“in to” vs “into” “Lookup” vs “lookup” button
MNO PQR
“make sure” vs “ensure” “rest” vs “hover”
“might” vs “may” Preposition vs Possessive use
“Name Number” vs “Name number”
“opens” vs “appears”
STU VWX
 “select” vs “click” “view‐only” vs “display‐only” or “read‐only”
“set up” vs “setup”
Spillman Technical Services vs Spillman 
Support
“the following” vs “this”
“to” vs “in order to”
YZ MISC
“you” is removed Cross‐refs do not include ‘see’ in link.
Cross‐refs use ‘For more info’ in paragraph form, 
and ‘See’ in bullet form.
Do not use contractions.

Documentation Writing and Style Guide 141


A

142 Documentation Department Writing and Style Guide

S-ar putea să vă placă și