FlexSim Style Guide

Created: July 2014

Updated: May 2020

Behind the history of innovation at FlexSim is our ability to communicate openly and
clearly with our users. This style guide is intended to facilitate and uphold our high standard of
customer service. We value effective and efficient decision-making processes and provide
software to assist companies large and small to make better business decisions. This means we
hold the responsibility of creating accurate, valuable, and accessible data in written content
produced for our users. Because of the diversity of our users, this style guide ensures an
established and user-friendly manner of communication.

Like FlexSim software itself, our style guide is meant to be intuitive and easy to use. This
style guide is not comprehensive, but instead should serve as a reference document to increase
our consistency across all areas of communication with our customers. FlexSim will refer mostly
to the Chicago Manual of Style, 17th Edition. This guide will supplement writing decisions made
therein by clarifying situations with more than one appropriate application and covering
situations that may not be discussed in Chicago at all. In some instances, this guide will also
emphasize issues that are covered in Chicago but repeatedly violated by publication writers and
editors.

This guide will also specify when written content at FlexSim should depart from the
Chicago Manual of Style and will direct writers in incorporating principles of global English.
These principles are drawn from John R. Kohl’s The Global English Style Guide: Writing Clear,
Translatable Documentation for a Global Market (2008, SAS Press: Cary, North Carolina). The
incorporation of these principles will improve communication with a global audience and
increase the FlexSim span of influence.
Contents
5 Grammar and Usage
5.1 Adverbs and Adjectives
5.2 Second Person
5.3 Active Voice
5.4 Moods
5.5 Positive Tone
5.6 Incomplete Sentences
5.7 Sentence Length
5.8 User-Friendliness
5.9 Efficiency
5.10 Simple Terminology
5.11 Use of “Dummy It”

6 Punctuation
6.1 Punctuation
6.2 Spacing
6.3 Em-Dashes
6.4 Lists

7 Spelling, Distinctive Treatment of Words, and Compounds

7.1 Spelling
7.2 Highlighting Key Terms and Expressions
7.3 Capitalization (see Glossary of preferred terms and formats)
7.4 Key names and keyboard shortcuts
7.5 Mouse Terminology
7.6 Link formatting
7.7 White Space in Code
7.8 Indentation in Code
7.9 Header Files and Guards in Code
7.10 Function Names in Code
7.11 Formatting for Code

8 Names and Terms

8.1 Titles and Headers

9 Numbers
9.1 Number Formatting
9.2 Money Formatting

10 Abbreviations
10.1 Abbreviations
5 Grammar and Usage
5.1 Adverbs and Adjectives
Adverbs should be avoided in almost every situation, as they are seldom necessary for clarity.
Descriptive adjectives should also be used sparingly and only when necessary. Other types of
adjectives, such as quantitative, demonstrative, and possessive, should be used normally when
needed. Note in the example that “blank” in “blank space” stays because it is necessary for
clarity.

A dashboard is a blank space that you can fill up with charts to display data.

NOT

A dashboard is a blank space that you can easily fill up with charts to clearly display
data.

5.2 Second Person

Write predominantly in the second person. Never use they or other third person terms such as
one or the user.

With this feature you can choose which components to install and which ones to file
away for later use.

NOT

With this feature the user can choose which components to install and which ones to
file away for later use.

5.3 Active Voice

A sentence is considered active when the main noun performing the action of the sentence is in
the subject position. A sentence is considered passive when the noun receiving the action is in
the subject position.
While there are times that passive voice can be effective and should be used, active voice is
usually preferred. Active sentences are usually shorter and more concise.

You can store up to 500 files in the database.

NOT

Up to 500 files can be stored in the database.

5.4 Mood
Pay attention to verb moods and use the mood that is the clearest in each situation. The three
moods are subjunctive, indicative, and imperative. The indicative mood will be used most often.
It is used to state direct facts and is the normal state of the verb.
 FlexSim software products can help you identify places where your production line
could be more efficient.

The imperative mood is used for requests and commands. It is formed by using the verb’s stem
to command or request something.

Select the Use Transport check box.

The subjunctive mood is not very common, and is most often used with the verb, to be. The
subjunctive mood expresses that something is not a reality but could be, as well as to make
suggestions.

We recommend that you be careful about opening email attachments.

5.5 Tone
Use positive phrasing wherever possible. While negative statements are useful for warnings,
positive statements are often more succinct and easier to comprehend and translate. Instead of
explaining what not to do, explain exactly what should be done. This makes English clearer for a
global audience, as suggested by Kohl 3.12.

Add a statement to the program to suppress messages.

NOT

Add a statement to the program to specify that messages not be displayed.

5.6 Fused and Incomplete Sentences

Use complete sentences in all materials except bulleted lists, where the information can contain
short, incomplete sentences. A complete sentence should be used to introduce lists.

You’ll resize the dashboard so it is bigger.

NOT

Resize dashboard.

BUT

In this step you’ll learn important skills, such as:

• How to add a chart to the dashboard

• How to create a pie chart
• How to customize a statistics collector

5.7 Sentence Length

Short sentences are less likely to contain ambiguities and complexities that impede reader
comprehension. For instructional, task-oriented information, limit your sentences to 20 words.
For conceptual information, a 25-word limit reaches the bounds of readability.
5.8 User-Friendliness
Put the customer’s needs first. Use a tone that is friendly, respectful, and encouraging to help
them navigate tasks. Use positive language wherever possible (see 5.5 for more information on
positive language).

Your files are backed up before installation.

NOT

Don’t worry about losing data. It’s backed up automatically.

5.9 Efficiency
Write with the intent to convey information as easily as possible. Use simple verbs and put the
most important information first. Avoid irrelevant details and unnecessary anecdotes. However,
be careful not to sacrifice clarity for efficiency. Be brief but detailed enough to be
comprehensive.
5.10 Simple Terminology
Avoid idioms, colloquialisms, and other kinds of metaphorical phrases. FlexSim reaches a global
audience and these phrases can be confusing to non-native speakers of English. Avoid slang and
jargon when possible and define any complicated jargon in simple terms within the text.

Back up the files by copying them onto a 1 terabyte hard drive.

NOT

Back up the files on a 1 TB hard drive.

5.11 Use of It is Sentences

Avoid starting sentences with it is. Instead, find a definite subject to begin the sentence with.
This makes sentences easier for non-native English speakers to understand.

Run the simulation model at this point in the process.

NOT

It is important to run your simulation model at this point in the process.

6 Punctuation
6.1 Punctuation
Proper punctuation placement should be observed in accordance with the Chicago Manual of
Style.
Exclamation points are unnecessary. A period is more neutral in tone and is preferred to end
sentences with in nearly every case. For simplicity’s sake, also avoid semicolons and minimize
the use of colons.
Although the program is reliable, you should save your model regularly.
Not
The program is reliable; however, you should save your model regularly.

6.2 Spacing
Always use a single space (rather than a double space) between the period of a sentence and the
first word of the next sentence. This provides consistency across FlexSim products and is in
accordance with standard practice.
6.3 Em-Dashes
Consider reordering the structure of sentences in order to eliminate em-dashes. One function of
the em-dash is to introduce clauses that are followed by a main clause, but one way to eliminate
them is to split the sentence into two sentences. This practice will improve reader comprehension
and will contribute to the clarity and consistency of the document. (See Kohl 8.5 for more on this
practice.)

A template is a single graphics element that you can resize, move, and delete. That is,
you cannot manipulate any part of the template separately, since it is only a placeholder
for the actual graph.

NOT

A template is a single graphics element that you can resize, move, and delete—that is,
you cannot manipulate any part of the template separately, since it is only a placeholder
for the actual graph.

6.4 Lists
For instructional lists, items must be prefaced by a grammatically complete sentence (subject,
verb, object) and may end in a colon to introduce the list. Items in the list may be bulleted (to list
a non-specific order of items) or numbered (if the items must occur in order), and they may be
grammatically incomplete sentence fragments. Regardless of sentence structure, items should
have parallel structure and have the first word capitalized. Parallel structure assists non-native
English speakers in their reading comprehension.

In this step you’ll learn important skills, such as the following:

• How to add a chart to the dashboard
• How to create a pie chart
• How to customize a statistics collector

7 Spelling, Distinctive Treatment of Words, and Compounds

7.1 Spelling
Since FlexSim is an American-based company, American spelling should be used (rather than
British English spelling). When issues of spelling arise, turn to Merriam-Webster’s dictionary for
clarification. Confirm all spellings with the same source to ensure consistency across all FlexSim
materials.
7.2 Highlighting Key Terms and Expressions
When setting off key terms and expressions from regular roman text, use italics for general key
terms and boldface for user interface terms. Do not use quotation marks (also known as scare
quotes) to set key terms and expressions apart, because this can indicate irony, doubt, or sarcasm.

A model in this sense is defined as a physical or mathematical description of an object or

an event.

Select the Use Transport check box.

7.3 Capitalization (see Glossary of preferred terms and formats)

Certain terms should be capitalized or contain capital letters.
2D, 3D, A-connect, FlexScript, FlexSim, FlexSim Healthcare, S-connect & User Manual.
Some terms should never be capitalized unless occurring at the beginning of a sentence.
dashboard, fixed resource, global tables, type, people objects, processor, task executor,
task sequence & toolbox
7.4 Key Names and Keyboard Shortcuts
7.4.1 Press
Use the word press to indicate that a user should push down on a key. However,
when a user should press a key without stopping, use the phrase press and hold
down.
7.4.2 Names of Keyboard Buttons

Capitalize keyboard key names, but do not put them in boldface.

Press Shift to capitalize a letter.

7.4.3 Punctuation
Always spell out names for potentially ambiguous keys such as the Plus Sign,
Minus Sign, Hyphen, Period, or Comma.
7.4.3 Key Combinations
To indicate when a user should press multiple keys in a sequence, use the Plus
Sign (+) between listing the keys.
 Press Control + Alt + Shift

7.5 Mouse Terminology

Use mouse button to indicate the left mouse button. Use right mouse button to refer to the right
mouse button.

Use mouse wheel to refer to the middle button on the mouse.

Use the verbs click, double-click, and right-click to refer to mouse clicks.
Use the term point to when you want a user to hover over an item without clicking it.
Use the verb drag, but not click and drag, drag and drop, or press and hold.
7.6 Link Formatting
In general, a link should not run longer than one line of text. If it does, try to find a shorter link
or use a hyperlink where applicable. When using hyperlinks, make sure that the text is as
descriptive as possible and under four words. The hyperlink should stand out from the
surrounding text, preferably with a blue font and underline.
I found all of my company’s efficiency needs by using FlexSim simulation software.
7.7 White Space in Code
Use acceptable amounts of whitespace while coding to increase readability, especially in HTML.
In CSS, avoid (<bt>) break tags unless you are creating paragraphs inside a table. Additionally,
use blank lines to divide tasks, and use comments to describe code (or code omissions) where
necessary.
7.8 Indentation in Code
All indentation in code should be made using tabs rather than spaces for maximum whitespace
and clarity.
7.9 Header Files and Guards in Code
Since FlexSim uses Visual C++ as our only compiler, headers can be guarded with #pragma
rather than #ifndef.
7.10 Function Names in Code
All global command names should be in lowercase, but class member functions should be in
camel case. Names should be descriptive and unambiguous, so avoid names with the prefix My.

7.11 Formatting for Code

All code should be simple, brief, and efficient. All code should follow the casing formats of its
respective language. Avoid long lines of code and separate them into different lines for optimal
readability.
8 Names and Terms
8.1 Titles and Headers
Chapter and section titles are written in all caps. Subheadings should be capitalized according to
Chicago 8.159. Capitalize the first and last words in the title and all other major words (nouns,
pronouns, verbs, adjectives, adverbs, and some conjunctions). Lowercase the articles a, an, and
the, as well as common coordinating conjunctions. Prepositions should be lowercase except
when they are used adverbially or adjectivally.

Welcome to the Style Guide

Best Practices for Designing Content

9 Numbers
9.1 Number Formatting
When using numbers, write out the number if it is between zero and one hundred. Otherwise, it is
acceptable to use the Arabic numeral.

After the company hired forty-two new employees, productivity increased by 543%.

If the number is a whole number followed by hundred, thousand, or hundred thousand, spell out
the number.

9.1.1 Percentages
Use the % symbol instead of percent to maintain clarity.
9.2 Money Formatting
Since FlexSim is an international organization with offices in Canada and Mexico, the form of
currency should always be specified to avoid confusion. (See Chicago 9.21.) Money should
always be listed in numeral form with currency symbols.

In 2019, FlexSim saved customers CAD $20,000, which is roughly equal to US $15,000.

NOT

In 2019, FlexSim saved customers $20,000 in Canadian money, which is roughly equal to
$15,000 in US money.

10 Abbreviations
10.1 Abbreviations
Avoid non-English abbreviations (i.e., e.g., etc.)
Common abbreviations such as 3D, 2D, HTML, JPEG, GIF, CPU, and others that can be found
in the Merriam-Webster dictionary are acceptable.
Periods are to be omitted when using acronyms (See Chicago 10.4).

Open the JPEG file.

NOT

Open the Joint Photographic Experts Group file.

Or

Open the J.P.E.G. file