Professional Documents
Culture Documents
Styleguide Documentationdept
Styleguide Documentationdept
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
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
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
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 Capitalization 88
Formatting Cross-References 96
Understanding the lack of indexes 97
Formatting Fonts 99
3 Responsibilities 125
Introduction 126
A Appendix A 133
Using function keys 133
Understanding computer terms 135
Basic guidelines
The following sections simply and quickly identify Spillman Documentation
style.
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.
bold Area names In the Narrative area, select the Narrative record.
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.
Courier Examples to enter (‘for Enter the first name of the person. For example, George.
font example’ only)
Message text A dialog box opens with the following message: Save a copy?
Spillman punctuation
The following table lists the punctuation conventions used by the
Documentation department.
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 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.
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.
Intro to a table The following table lists buttons on the main toolbar.
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.
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.
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.
Select Action used to select menu options or check To open the Names screen, from the Tree
boxes. Menu, select Hub Menu > Names Table.
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.
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
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 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.
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 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.
ay ey gray, grey
e ae archeology, archaeology
e oe fetal, foetal
er re fiber, fibre
f ph sulfur, sulphur
l ll traveled, travelled
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
forward forwards
toward towards
fall autumn
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
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.
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.
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.
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.
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.
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.
This table lists the settings for the module. The following table lists the settings for the
module.
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
Correct examples
Correct examples
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.
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.
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.
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.
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.
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.
Incorrect Correct
Use the Commands menu to dispatch a Select Command > Dispatch Call to
call. dispatch a call.
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.
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.
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.
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.”
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.”
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.
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.
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.”
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.
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.
The following table lists common symbols, their names, and their keyboard
shortcut.
@ At symbol Shift+2
^ Caret Shift+6
* Asterisk Shift+8
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.
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
abbreviate shorten
abort cancel
accordingly so
activate start
antithesis opposite
autonomous independent
beverage drink
commence begin
component part
concept idea
concur agree
conjecture guess
currently now
deficit shortage
demonstrate show
discourse talk
duplicate copy
elucidate clarify
exhibit show
fracture break
gradient slope
incinerate burn
incision cut
incombustible fireproof
inform tell
initiate begin
inundate flood
locate find
manufacture make
moreover besides
obtain get
orientate orient
perspective view
posterior rear
prior to before
purchase buy
ramification result
request ask
sophisticated complex
subsequent next
sufficient enough
transmit send
utilization use
utilize use
verification proof
viable workable
by means of by
continue on continue
in between between
open up open
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.”
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.
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
When there are multiple ways to perform a task. Match the
description order to the order the methods are listed.
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).
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.
dots per inch DPI For more information, see “Use screen
shots” on page 70.
for example, such as e.g. or i.e. Do not use the abbreviations. Always use
for example or such as.
miles mi No period.
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.
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.
soul soul
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
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.
tasks required for the specific module. Make sure to document the default
values of application parameters, settings, and environment variables.
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
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.”
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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...
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.
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.
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.
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.
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.
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.
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.
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.
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.
Never use the following construction: The screen displays. Use The screen is
displayed, or the preferred, The screen opens.
NOTE
For information on bulleted lists in tables, see “Formatting table paragraphs” on
page 117.
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
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,
Correct
Correct
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
Correct
Correct
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
Select the Vehicle Table Reports Menu from the Hub menu.
Correct
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
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
Press To
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}
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 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.
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.
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
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.
bold Area names In the Narrative area, select the Narrative record.
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.
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.
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.
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.
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.)
Table names (Note that the table name Open the Names screen (nmmain).
comes after the screen name in
parentheses.)
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.
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 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.
Incorrect Correct
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.
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.
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
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.
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 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
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 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.
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.
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.
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.
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
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.
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.
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.
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
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.
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.
To Do this
Open the Names screen (nmmain) At the command line, enter names.
Application When describing application parameters, use the following column heading,
parameters and one of the following row designs.
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
Module and When describing module or system settings, use the following column
system settings heading, and one of the following row designs.
allowTempRelWithBonds True/False
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.
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.
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.
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.
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.
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.
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
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.
GoTo Ctrl+O Number the fields so that a field can be selected to modify.
Insert Ctrl+R Switch between the Ins and Ovr key-in modes.
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.
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.
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).
Term Definition
AIX A UNIX operating system created by IBM. Use the phrase AIX operating system as opposed to just
AIX in documentation.
client The computer or application on a computer that communicates with the server.
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.
FTP Abbreviation for file transfer protocol. Even though developers might, do not use FTP as a verb, or
to mean file transfer.
Term Definition
ISP Abbreviation for Internet Service Provider. Do not use ISP provider.
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.
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.
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.
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.
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.
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.
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.
delete
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
align vertically
broken character
indent or insert em quad space
begin a new paragraph
spell out
set in CAPITALS
set in lowercase
set in italic
set in roman
set in boldface
hyphen multi-colored
en dash 1965–72
superscript or superior
subscript or inferior
centered
comma
apostrophe
period
semicolon
colon
quotation marks
parentheses
brackets
query to author: has this been
set as intended?
push down a work-up
wrong font
1The last three symbols are unlikely to be needed in marking proofs of photocomposed
matter.
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
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.