FlexSim Style Guide

Tutorial Overview

Each tutorial should have a topic that is dedicated to forecasting the entire tutorial. This overview is a separate topic (with its own page).

In the first portion of the overview, you'll explain the high-level concepts taught by the tutorial and give general details about the simulation model the user will build in the tutorial. At the end of this section, you should include an image or animated gif of the final simulation model that will be built in the tutorial.

In the next section of the overview, you'll provide links to the individual tutorial tasks and provide brief summaries of each one.

In the last section of the overview, you can link to concept topics in the main body of the User Manual for more information. This section of the overview is optional if conceptual topics haven't yet been developed for the tutorial.

Keep in mind the following naming conventions:

• Never name the Tutorial Overview file Overview.html. Rather, try to give the file a more specific name that is unique to that specific tutorial. Having multiple files with identical names will cause problems when converting the User Manual for the web.
• Tutorial tasks and steps should always be given a task-oriented name that is written in the imperative mood.

Tutorial Tasks

These topics are the main content of the tutorial. Each tutorial task should provide an overview and instructions for building a specific phase of the simulation model in the tutorial. Generally, each tutorial should have at least two tutorial tasks. Tutorial tasks are also separate, distinct topics (with their own pages). These tasks are a group of tutorial steps that explain how to build a specific phase of a simulation model. If possible, these tasks should be organized around teaching a general modeling concept or a specific feature of a tool.

Tutorial tasks should always begin with a mini table of contents that outlines the sections of the tutorial.

After the table of contents, the first section should be an overview section that summarizes the various steps and learning objectives for the tutorial. It should also include an image or animated gif of the simulation model that will be built by the end of the tutorial tasks. If needed, the overview can also include a section that explains key concepts related to that tutorial task or links to other relevant concept topics.

The main body of the tutorial task will contain tutorial steps. Each tutorial task should contain at least two or more tutorial steps. As a general rule, the technical writer recommends organizing the tutorial steps after the following pattern:

1. Build the 3D Model - Tutorials should start with building the 3D model, which generally includes adding 3D objects, naming 3D objects, connecting objects, and possibly setting some object properties. You should include an image of the 3D model near the beginning of the step.
2. Add Activities to the Process Flow - The next step usually involves instructing the user to create a new process flow, add flowchart shapes and activities to the process flow, renaming the activities, and connecting the activities. Generally in this step, you're just building the basic layout of the process flow logic without editing its logical properties. You should include an image of the process flow near the beginning of the step.
3. Create the Model Logic - In this step, you'll instruct the user to edit the properties for each activity in the process flow and connect it to the 3D model. In the introduction to this step, you should always include a table that explains how each activity will work logically.
4. Run the Model - In this step, the user will run the model and see how the model logic controls the 3D objects during a simulation run. This step can also be used to discuss the pros and cons or key concepts related to the previous tutorial steps. If needed, you can attach a model run to the end of the task in which you build or modify model logic instead. Including animated gifs of the model run is highly encouraged.

Where only small changes are being made to a model (such as in later model building phases), you can potentially consolidate these different phases into a single step as needed.

The end of the tutorial task should include a conclusion that indicates the entire tutorial is either finished or links to the next tutorial tasks. If desired, the conclusion can also include a discussion of pros and cons of different model building methods that have been covered in the tutorial up to that point.

Tutorial Steps

Tutorial steps are sub-sections of tutorial tasks. They consist of a general overview of the step and then an ordered list containing the specific instructions for completing that step.

The following style guidelines apply when writing tutorial steps:

• Individual steps in must be given a title that is task-oriented and written in the imperative mood.
• Each task should contain a brief overview of the step. If key concepts related to that step need to be explained, those concepts should be explained in the overview.
• The specific instructions for each step should be formatted in an ordered list and the content in that ordered list should follow the The FlexSim User Interface (UI) Guidelines.
• The ordered list of instructions should not contain more or less than 5-20 steps in order to keep the steps focused and simple. If it exceeds this limit, consider breaking the step into two different steps. If you decide to break this rule, make sure you do so for a good reason, such as it being nonsensical to break up a large set of steps into two smaller sets of steps.
• If an explanatory note is needed in the instructions section of a step, you should use a tip box.
• Often when you are instructing users to edit a 3D object or process flow activity, the user will need to change more than one property at a time. The directions for editing each property should be its own step. At the end of a set of steps for editing the properties of one object or activity, you should include a screenshot of the property settings for clarification.
• When instructing users to edit a property that requires them to change the text of a property, instruct them to delete the property's current text first to avoid confusion.
• All tutorial topics should use the FlexScript code highlighting CSS. Whenever you're telling the user to type something into a property, it should be formatted in <code> brackets. When the code is displayed it will use code highlighting, such as 2.00 or token.operator.
• If a sentence ends with code highlighting, you can still end it with a period. Since the code highlighting doesn't encapsulate the period, it should hopefully not confuse users too much.

Main Menu

Menus are groups of commands organized into categories such as File, Edit, View, etc. The FlexSim main menu bar is near the top of the window. The following are some guidelines for discussing menus in technical documents for customers:

• Remember that menus contain commands. Avoid referring to a menu command as a choice, an option, or a menu item. Always surround menu names with the words the and menu in procedural documents.
• When referring to a specific menu, capitalize the name of the menu, but use lowercase for the word menu, as in "the File menu."
• Use the verb select to describe how a user should interact with menus and menu commands. Don't use words such as choose, click, or pick. If you want to tell a user how to open a submenu, tell them to point to a command on the main menu and then click the appropriate command. Avoid using angle brackets > for submenu items.
• Menu names and menu commands should be in bold typeface in customer-facing documentation.
• Don't use adjectives such as cascading, drop-down, pull-down, pop-up, shortcut, or submenu to describe menus unless you want to emphasize a product feature or are writing to software developers.
• Refer to unavailable menu commands as unavailable, not as dimmed, or grayed since those words could potentially seem unprofessional or even offensive to certain audiences. You may use the term dimmed to describe the appearance of an unavailable command, but not grayed. You can use the term disabled to refer to unavailable commands, but remember to do so with caution and sensitivity.

Toolbar

A toolbar is a group of commands optimized for easy access. Unlike a menu, which contains a comprehensive list of commands, a toolbar contains the most frequently used commands. The FlexSim toolbar is a Graphical User Interface (GUI) with button icons for the most frequently used commands. A few of the toolbar buttons have submenus, which are indicated by the arrow next to the icon. The following are some guidelines for discussing toolbars in technical documents for customers:

• When referring to toolbar elements, use the term button. Do not refer to a toolbar button as a choice or an option. Also, do not refer to a toolbar button as a toolbar item or a toolbar control except in content for software developers about the user interface. When giving instructions about toolbar buttons, you can simply use the command name, such as "click Save on the toolbar."
• When referring to a specific toolbar, use lowercase for the word toolbar, unless the word Toolbar appears in uppercase in the user interface. Toolbar is always one word. You can also simply refer to the main toolbar as the toolbar.
• To describe user interaction with toolbars and toolbar buttons, use click for toolbar buttons and submenu commands, and click, type, or enter if a submenu command requires users to provide information. Do not use choose, select, or pick.
• Toolbar buttons should be in bold typeface in customer-facing documentation.
• A toolbar item with a submenu is called a menu button if the user can click either the button or the arrow to open the submenu. For submenus, use the words the and menu with toolbar menu buttons, but do not use the word button, such as "click the Create Objects menu on the toolbar, and then click Create Objects."
• In content for a general audience, do not add any extra descriptors to the term toolbar such as cascading, drop-down, pull-down, pop-up, or submenu unless the way that the menu works needs to be emphasized as a feature of the product. Avoid using angle brackets > for submenu items.
• Refer to unavailable menu commands as unavailable, not as dimmed, or grayed since those words could potentially seem unprofessional or even offensive to certain audiences. You may use the term dimmed to describe the appearance of an unavailable command, but not grayed. You may use the term disabled, but please do so with caution and sensitivity.

Control Bar (Formerly Simulation Control Panel)

The control bar, also known as the simulation control bar, refers to the commands that are used to reset, run, stop and otherwise control simulations. It contains both text and Graphical User Elements (GUI) such as icons that resemble the playback functions on a video or music player.

In the past, the control bar has typically been referred to as the Simulation Control Panel. While this phrase is an accurate description of the UI element, the term control panel might be confusing because of it is used in the Windows UI as a way to change basic systems settings. FlexSim uses this term in a completely different way.

The following are some guidelines for discussing the control bar in technical documents for customers:

• The control bar contains buttons. Do not refer to a control bar button as a choice, an option, or as controls. The first time you discuss a control bar button, use the specific button name surrounded by the words the and button, as in "the Reset button." You can possibly omit the words the and button if it is immediately apparent from the context that you are referring to a specific button on the control bar.
• When referring to the control bar, use the lowercase word control bar or simulation control bar.
• To describe user interaction with the control bar, use click or press. Do not use choose, select, or pick.
• Control bar button names should be in bold typeface in customer-facing documentation.

Panes (Library, Quick Properties, Etc.)

Panes are a framed section of a window. FlexSim uses panes extensively throughout its UI. Some of the common panes are:

• Left pane - Contains the Library and the Toolbox. The contents of the Library change based on what kind of window is open in the center pane.
• Right pane - Contains the Quick Properties pane.
• Bottom pane - Usually closed by default, this displays error messages, typically. However, it can also contain the Animation pane and other features.
• Center pane - Contains the 3D Model View by default. This pane can also be used to display various windows or tabs such as process flows, the Flow Item Bin, the dashboard, or the User Manual, the Tree View, etc. The center pane can be split into multiple windows that can be viewed simultaneously (which is the default) or the windows can be re-arranged as tabs on the center pane to be viewed one at a time.

A few panes, such as the Library and Quick Properties, have content that is context-sensitive, which means the content varies depending on the object currently selected or displayed in the center pane. These panes also have submenus that can be expanded or collapsed by clicking the progressive disclosure controls: the + or - sign or arrows next to the menu title.

The following are some guidelines for discussing these panes in FlexSim documentation:

• Do not refer to panes as panels. The term pane is used more commonly in documentation. NOTE: Microsoft possibly coined the use of the term pane in a software context because their operating system was named Windows. Because actual windows contain panes, that may have been the inspiration for the term.
• Refer to each pane by the title of its content rather than its location, such as the Library, the Model View, Quick Properties, etc. However, when the pane is currently displaying something different than its normal content (such as when Tree Navigation is being displayed in the right pane), refer to that content by both its title and location, such as "Tree Navigation in the right pane."
• When you are referring to a pane by the title of its contents, use the same capitalization that is used in the UI, e.g. the Library, Quick Properties, etc. If you are describing the pane's location rather than its title, use lowercase letters instead, such as "the center pane."
• Generally, you should not bold the names of panes. However, you can bold the names of submenus on panes.
• On panes that have submenus such as the Library and Quick Properties, refer to the individual submenus by their titles alone, such as "in the Quick Properties pane under Statistics." Do not do not add any extra descriptors such as submenu, accordion menu, accordion pane, cascading, drop-down, or pull-down. If you must use an extra descriptor, use the term group instead, such as "in the Quick Properties pane under the Statistics group."
• When talking about the progressive disclosure controls, just refer to the individual controls by name or by its symbol. Use the verbs expand and collapse to refer to these actions, such as "click the plus sign (+) next to Statistics to expand it."

Tabs

A tab is a feature that allows one or more panes to be contained within a single window. By default, FlexSim splits the center pane when a user opens a feature such as a Statistics dashboard, the User Manual, or Tree View. As an alternative to splitting the center pane, users can dock these windows as tabs in the center pane for easier access. The following are some guidelines for discussing tabs in FlexSim documentation:

• Always surround tab names with the words the and tab in procedural documents. When referring to a specific tab, capitalize the name of the tab, but use lowercase for the word tab, as in "the Statistics tab."
• Use the verb click to describe how a user should interact with tabs.
• Tab names should be in bold typeface in customer-facing documentation.

3D Objects

In FlexSim, 3D objects are the basic building blocks of a simulation model. Using various objects from the FlexSim library, users can design and test the process or system they want to simulate. Each type of object has unique properties and functions. For example, a source creates new items, a transport moves items from one space to another, a processor delays or changes items in some way, and so forth.

The following are some guidelines for discussing objects in FlexSim documentation:

• When referring to a specific object or type of object, use the actual object's name, such as source, processor, conveyor, etc. In a tutorial, you should refer to the object by the name you told the user to assign it, such as Processor3, Rack5, Queue2, etc. Avoid surrounding the object name with the words the and object.
• You do not need to capitalize the name of the object unless you are referring to a specific object in a specific model.
• Use the verb click or double-click to describe how a user should interact with objects. When you want to instruct users to drag an object from one space to another, use the verb drag instead of click and drag. Don't use words such as choose, select, or pick.

Items

In FlexSim, items are abstract items that move (flow) through the simulation model. By default, flow items are graphically represented as brown boxes in FlexSim.

The following are some guidelines for discussing flow items in technical documentation:

• Only use the term flow item or item to refer to flow items. Avoid referring to items as flowitems or boxes. Only refer to items as objects when discussing them in a very general sense, such as when giving a high-level overview of how FlexSim works. However, if you are working one-on-one with a customer who has a specific item in mind that will be represented by the items in the simulation model, it is acceptable to substitute the name of that item for flow item.
• Do not capitalize the term flow item.
• The term flow item is never in bold typeface.

Port Connections

In FlexSim, port connections are used to connect one object to another. There are two types of port connections in FlexSim:

• Input/Output ports: These ports are used to determine how an item passes from one object to another. When an output port on one object is connected to the input port of another object, the item will pass from the first object's output port to the next object's the input port.
• Center ports: When the center ports of two objects are connected, it creates an abstract reference point between those two objects. Center ports enable objects to communicate or interact in complex ways.

Users create ports using the Connect Objects tool or various keyboard shortcuts. Users remove ports using the Disconnect Objects tool or keyboard shortcuts.

Port connections can be difficult to document and describe clearly. With that in mind, please follow these guidelines closely when writing about them:

• Avoid using the term port by itself unless you are discussing the concept of ports generally. In most cases, you should probably refer to a port specifically as an output port, an input port, or a center port. Keep in mind that users will almost always assume you are referring to an input/output port when you use the generic term port. For that reason, you should take great care to use descriptive adjectives to refer to specific port types, especially center ports.
• In general, you should refer to connections between ports as port connections. When discussing center port connections specifically, you should always use the full term center port connection for clarity.
• You can add the term A-connect or S-connect in parentheses for clarification when directing users to make a port connection.
• The terms port and port connections should not be capitalized. The descriptive terms center, input, output, open, or closed should also not be capitalized.
• Use the verb connect to describe the process of making port connections. However, when using the verb connect, make sure that it is clear from the context: 1) which type of port connection the user should make, 2) which object should have the output port or the input port, and 3) which port will have highest priority when the object is potentially pushing flowitems to multiple objects. In other words, make sure that you clearly indicate the precise order that objects should be connected when instructing users to connect two objects. Also make sure that you are clear what type of connection users should make.
• Alternatively, you can use the phrase create a port connection to describe how users should connect one object to another, such as "create a port connection from Source1 to Queue2." When using this phrase, make sure you use the prepositions from and to (in that order) to clarify which object the user should click first and which object they should click second. Use the full phrase create a center port connection when you are specifically discussing center ports.
• In general, try to avoid using the phrases connection mode and disconnection mode. Try to only use these terms to describe what happens when a user is using the Connect Objects tool or Disconnect Objects tool or related keyboard shortcuts. If it is necessary to use these terms, use the phrases turn on or turn off, such as "turn on connection mode" or "turn off disconnection mode." Do not use the phrase enter or exit to describe how users turn connection and disconnection mode on or off.
• See the section on Key Names and Keyboard Shortcuts for information on discussing keyboard shortcuts related to port connections.
• Because port connections themselves cannot be clicked directly, they should not be formatted in bold typeface in documentation. Because the Connect Objects and Disconnect Objects tools are clickable, they should be in bold typeface.

Picklists

Picklists are pre-programmed functions that have been created by the FlexSim development team to simplify common tasks or options in FlexSim. For example, there are picklists that can change the shape and color of an item or that can change the rate at which particular events occur in the simulation.

The following are some guidelines for discussing picklists in FlexSim:

• Picklists should be referred to using the term picklist, not as pick lists.
• In general, try to minimize the use of the term picklist as it is jargon that is unique to FlexSim. You can simply refer to the picklist by name.
• If you need to refer to the actual drop-down list or field in a picklist, you can refer to those as picklist options.
• Do not capitalize the term picklist. When referring to the names of specific picklists, mirror the capitalization that is used in the user interface.
• Usually, users select picklists from various drop-down menu lists in the Properties Dialog Box or Quick Properties pane. For that reason, you can use either the verb click or select to refer to the process of selecting a picklist from a drop-down list.
• The term picklist should not be in bold typeface. However, the names of specific picklists should be in bold typeface, especially when you are instructing users to click on the picklist name in a drop-down menu list.

Triggers

Users can define a trigger to execute a particular set of code during the simulation. Generally, triggers will execute at specific points during the simulation run.

The following are some guidelines for discussing triggers in FlexSim:

• When referring to a trigger, refer to it using its specific title, mirroring the spelling and capitalization used on the user interface.
• Format the names of triggers in bold typeface.

Check Boxes

A check box is a square box that is selected or cleared to turn an option on or off. Follow these guidelines when discussing check boxes:

• When referring to a check box, format the check box title in bold typeface. Always surround the title with the words the and check box.
• Use the verb check to tell users to put a check in a check box. Use the verb clear to tell users to remove a check from a check box. Avoid using select or uncheck to instruct users what to do with check boxes.

Group Boxes

A group box is a frame or box that encloses a set of related options. In some programs, a group box can be indicated by a single line that unifies the options below it. For example, in the image below, Output and Input are both two different group boxes. The following shows an example of a group box in FlexSim:

Follow these guidelines when discussing group boxes:

• Keep in mind that group boxes are usually only visual devices, not actual elements of the user interface. However, pointing out group boxes to users can help direct their eyes to the appropriate part of the screen.
• When discussing group boxes, you can decide whether you need to mention the title of the group box for clarity or not. If you decide to use the group box title, you can introduce it using either the prepositions under or in, followed by the title of the group box, followed by the word group or area.
• Group boxes titles should be formatted in bold typeface.

Key Names and Keyboard Shortcuts

Follow these guidelines when discussing keys and keyboard shortcuts in FlexSim:

• Use the verb press to refer to the action of pressing a key. Use the phrase press and hold down to tell users to press a key continuously unless it is obvious from the context that they should do so. Use the verb type to refer to the action of typing a key or a phrase on a keyboard.
• When telling a user to press a key, spell the key names as they appear on the keyboard. Capitalize the key name.
• When telling users to press a letter key, capitalize the letter. Do not format the key in bold typeface.
• When telling a user to type a letter key, use a lowercase for the letter and use bold formatting, unless an uppercase letter is required.
• On first mention, you can use the definite article the and key with the key name if necessary for clarity. For example, "the F2 key." On subsequent mentions, refer to the key only by its name. For example, "press F2."
• Because special character names could be confused with an action or could be difficult to see, always spell out the following character names: Plus Sign, Minus Sign, Hyphen, Period, and Comma. It is acceptable to add the symbol in parentheses to avoid confusion if needed.
• When explaining keyboard shortcuts, you can refer to a key combination or a key sequence by the keys that make it up. To specify a key combination, use the plus sign between the keys to be pressed. You can also use commas and spaces to indicate the sequence of keys to be pressed.

Links

Links enable a user to go to another page, window, or Help topic. They can also be used to possibly display a definition, initiate a command, or select an option. A few guidelines for formatting links:

• When creating hyperlinks, the important thing to pay attention to is the actual text that will be linked. Use text that is as descriptive as possible, preferably the title of the destination page or document you are linking to.
• Limit link text to four keywords or fewer, if possible. Short links are easier to scan.
• Never use phrases like click for more info or click here as the hyperlinked text. Don't use a long URL as the hyperlinked text.
• Use a consistent CSS style for hyperlinks that makes the hyperlinked text stand out as an obvious hyperlink, such as a blue underline.

List Boxes and Drop-Down List Boxes

A list box is any kind of box containing a list of items the user can select. A drop-down list box is a closed version of a list box with an arrow next to it. Clicking the arrow opens the list. Follow these guidelines when discussing list boxes and drop-down list boxes:

• When referring to list boxes, format the list box title in bold typeface. Always use the word the before the list box title. After the list box title, use either the term list or box, whichever is clearer. Avoid referring to it as a drop-down menu or pull-down menu.
• Use the verb click or select to tell users which selection they should choose from the list box.
• If you are instructing users to select a specific item in the list box, format the selection title in bold typeface as well.

Mouse Terminology

Follow these guidelines when instructing users how to use a mouse with FlexSim:

• Use mouse devices if you need to refer to more than one mouse.
• Use mouse button to indicate the left mouse button. Use right mouse button to refer to the right mouse button. Do not use mouse button 2 or secondary mouse button.
• Use mouse wheel to refer to the third or middle button on the mouse. Use the term scroll in and scroll out to refer to mouse wheel movement. The term rotate is also acceptable.
• Use the pointer to refer to the mouse pointer. Do not use the term cursor.
• Use the verbs click, double-click, and right-click to refer to mouse clicks. Always include the hyphen for double-click and right-click. Do not use the terms choose, select, or pick to refer to mouse clicks.
• When you want to tell users to put their mouse over an item without clicking it (such as when opening a submenu), use the term point to. Do not use > marks and do not use the term hover.
• Use the term drag, but not click and drag, drag and drop, or press and hold.
• Do not combine keyboard and mouse actions as if they were keyboard shortcuts, such as shift+click.

Option Buttons (Radio Buttons)

An option button, also sometimes called a radio button by developers, is a round button used to select one of a group of mutually exclusive options. Follow these guidelines when referring to option buttons:

• Refer to option buttons by their label or their title. In other words, refer to buttons by the text that is next to the button. Do not use the term option, option button or radio button to describe what users should click.
• Use the verb click or select to describe how a user should interact with option buttons. Don't use words such as choose or pick.
• Format option button labels in bold typeface.

Spin Boxes

Spin boxes are text boxes with up and down arrows that users click to move through a set of fixed values. The user can also type a valid value in the box. The following image is an example of a spin box:

The following are some guidelines for discussing spin boxes:

• In content for customers, simply refer to the spin box by its label. For example, the X-Position box. Only use the term spin box when writing for a technical audience.
• Do not use the term spinners or other labels to refer to spin boxes.
• Format the labels of spin boxes in bold.

The previously mentioned guidelines can be especially challenging because some spin boxes in FlexSim (such as the one pictured above) have complex labels using that are both unnamed and named. In these cases, make sure that it is clear from the context which box you are referring to.

Start Screen

The Start Screen is the beginning screen that displays after FlexSim has finished loading. The Start Screen essentially acts as a portal, giving users a chance to quickly start a new project or open an existing project. It also provides new users with links to help them learn how to use FlexSim. The following illustrates how the Start Screen looked in a previous version of FlexSim:

The only general guideline to follow when discussing the Start Screen page is to format anything that is clickable in bold typeface.

Text Boxes and Drop-Down Combo Boxes

A text box is a rectangular box in which users can type text or numbers. If the box already contains text, the user can select the default text or delete it and type new text or numbers. Drop-down combo boxes are text boxes with list boxes attached. Follow these guidelines when discussing text boxes and drop-down combo boxes:

• When referring to a text box, format the text box title in bold typeface. Always surround the title with the words the and box.
• Use the verb type to refer to the process of entering text in the text box. You can also include the word enter if there is no chance of confusion. If you are instructing the user to select an item from the drop-down combo box, use the term click or select.

Unnamed Buttons

Some buttons in the FlexSim User Interface have graphics rather than text. If you refer to an unnamed button that appears in the interface, use the name of the tooltip, and then insert a graphic showing a picture of the button, if possible.

General Guidelines

The following general guidelines apply to HTML and CSS files in the User Manual directory:

• Thou shalt not change the CSS. Changes to the CSS are considered major changes and should be made in consultation with the major stakeholders, including the FlexSim technical writer.
• HTML files should use line breaks. Line breaks help developers or other content reviewers to review the differences from one file to another within Mercurial. The technical writer recommends using a tool to guide when a line break should occur. For example, if you use Notepad++, you can open the Settings menu and select Preferences. In the Editing settings in the Vertical Edge Settings group, you can check the Show vertical edge checkbox and set the number of columns to 100. This will create a blue line in your editor that suggests where you should break a line. It helps to keep your line breaks consistent.
• Use indents to indicate a tag is nested in another tag. If you have nested a tag within another tag, it should be indented inside that tag to keep the HTML page well-organized and easy to read.
• You can never use too much white space. Don't be afraid to use white space (hard returns) between content, such as between two <li> tags in a list or between two <p> tags. Using white space liberally increases the HTML file's readability.
• Use CSS to create white space rather than <br> tags. You should avoid using break tags in general. The only exception to this rule is that you can sometimes use break tags to create paragraphs inside table cells.
• In reference topics, format descriptions of multiple buttons in a table. If you need to describe what each button in a UI does and there are multiple buttons, format those buttons in a table.

Heading Tags

The following table discusses the rules for the kind of content that should use heading tags. NOTE: In general, you should not go any deeper than an h4 tag in User Manual content. If you need more sub-sections in a given topic, you should try to reorganize it rather than use more nested headings.

Section Tags and Anchor Links

The User Manual uses the HTML 5 <section> tag in all topics. The following guidelines apply to this tag:

• Each topic should be divided into logical sections. Every topic should be broken up into multiple sections that follow good organization principles. The content in these sections should be nested within <section> tags.
• Each section in a topic should be given a unique ID. Assign a unique id to each section. This section ID will take the place of <a name> tags when creating anchors when linking to content within a page.
• Every section should first contain an h2 tag. Every section tag should start with a title to that section, formatted in h2s.
• Subsections (which start with an h3 tag) do not need to be their own nested section tag. Subsections can simply be contained within a single section tag. If you feel that the HTML file would be easier to read by adding nested section tags for subsections, you can add it at your discretion.

Mini Table of Contents and Nav Tags

Nearly every topic should begin with a mini table of contents, unless the topic is too short to be divided into more than one section. Mini table of contents will use the HTML 5 <nav> tag that contains an unordered list of the various sections in the topic. The following guidelines apply to this tag:

• The mini TOC should exactly correlate with the sections in the topic. The mini TOC will link to each section using the section's ID as the anchor tag.
• Mini TOCs should only contain links to sections, not to subsections. You only need to link to section headings that go as deep as h2, not h3.
• Section titles should not be longer than one line in the mini TOC. If a section title is so long that it breaks over multiple lines in the mini TOC, that section should be renamed until it fits.
• Mini TOCs for tutorials are formatted slightly differently. Mini TOCs for tutorials should include unordered links to the tutorial's introduction and conclusion. The steps of the tutorial should be formatted in an ordered list.

Bold and Italics

Formatting text in bold and italics can help guide the eyes of your reader to the most important part of the sentence. It can also help them to easily scan documents for relevant information. This section will explain how to correctly format code in bold and italics.

In the FlexSim User Manual, words should generally only be bolded when you are writing in the instruction mode (and it should generally be formatted in an ordered list). When you are writing in instruction mode, there are two possible reasons for formatting text in bold, as explained below. You should use different classes for these <strong> tags to indicate your purpose in using these tags:

1. User Interface Elements: When you format text in bold because it is an element in the user interface, such as a clickable UI element, use the class "gui" in the <strong> tag.
2. Inline Heading: To bold something as an inline heading, such as the first word or phrase in a list item, use the class "heading" in the <strong> tag.

Text can be formatted in italics if you want to introduce a new term or if you want to emphasize a word or phrase.

NOTE: You should always use the <strong> tag to format a text element in bold. Never use the <b> tag. To format a text element in italics, use the <em> tag. Never use the <i> tag.

Tip Boxes and Important Notes

Also sometimes referred to as callout boxes, tip boxes and important notes help readers learn how to get the most out of FlexSim software. Tip boxes and important notes also add some visual variety to the document and help draw attention to helpful points you want your audience to notice. This section will discuss how to format the code for tip boxes and important notes.

Tips and important notes look very similar, but are quite different in purpose. You should consider your purpose carefully when deciding which format to use:

• Tip Boxes: Used for text that is relevant to the topic, but not necessarily within the goal or scope of the topic, such as a side note or afterthought. You should use the <aside> tag with a class="tip" for tips.
• Important Notes: Used for emphasizing important information that might otherwise get lost in the text. You should use the <aside> tag with a class="important" for important notes.

The following style guidelines apply to both tips and important notes:

• Every tip or important note should have a title. Every aside should contain a title, using the h4 tag. This title should describe the topic of the tip so that users can quickly get the point of the tip or important note.
• Use paragraph tags for the content of the tip or important note. The rest of the content should be formatted inside <p> tags. You're welcome to use multiple <p> tags if you need to break up the content into more paragraphs.

Table Tags

The following guidelines apply to the <table> tag and the related <tr>, <th>, and <td> tags:

• Use the <th> tag for table headings. The first row in a table should always include table heading tags.
• Use line breaks and white space liberally. Table tags should include line breaks and ideally some white space in between content such as two <td> tags.
• Use indents for nested tags. Tables are especially difficult to read if you don't indent your nested tags.
• Use class headings in <th> tags to set the column width. To set the width of a column, assign it a class with the percentage you want the the column to be. For example, <th class="twentyfive"> to set the width to 25%. The CSS will do the rest. Just remember that all the columns in the table should equal a total width of 100%.

Images and Callouts

Use the following classes for images:

The following additional style guidelines apply to images:

• Screen captures should be a maximum of 700 pixels wide. Capture only what is absolutely necessary to convey the information the user needs. For example, if you are documenting the fields in a tab pane, you should capture just the tab pane itself, and crop out images of other tabs. Do not capture the whole window if you don't have to.
• Don't include extra information in an image tag. In the image tag, include only the src and class tags (as specified above). Don't add any alternate text or IDs to the image.
• Direct users to images in the body of the text. In the body of text, use the verbs preceding and following to direct readers to the appropriate image.
• Match the capitalization of images. Try to match the capitalization of the images when linking to the file. The capitalization can affect whether the image displays correctly in certain web browsers.

Unless there are specific reasons for deviation, the following rules should apply to callouts in images.

• Callouts should use 12pt Arial font.
• Arrows and text should be black and arrows should be sized to match the 12pt font.
• Use drop shadows for arrows and callout text, but only give the drop shadow a few pixels offset. For text, the drop shadow should not be so dramatic that it makes the text hard to read.
• Callouts should be placed in a blank area of the image, not jumbled into a high-density area.
• Don't surround the callout with a bubble caption. Just leave it as drop-shadowed text.

WebKit Open Source Project Exceptions

FlexSim follows the Webkit coding style guidelines, which can be found at the WebKit Open Source Project. However, there are some exceptions, as discussed in the table below:

Formatting Code Examples for Users

The following guidelines come from the Microsoft Manual of Style, 4th edition. Code examples can be an effective way to teach users about FlexScript. You can possibly include:

• Simple, one-line examples interspersed with text
• Brief, self-contained examples that illustrate specific points
• Lengthy samples that illustrate multiple features, complex scenarios, or best practices

To create useful code examples, first identify the tasks and scenarios that are meaningful for your readers, and then create examples that illustrate those scenarios. Code examples that demonstrate product features are not useful unless they explicitly address the problems developers are trying to solve.

The following are some general guidelines to follow when creating code examples:

• Create concise examples that exemplify key development tasks. Start with simple examples and build up complexity after you cover common scenarios.
• If you can't provide examples for all programming elements, focus on frequently used elements and elements that may be difficult to understand and use.
• Don't create code examples that are too complex to scan or understand easily. Reserve complicated examples for tutorials and walkthroughs, where you can provide a step-by-step explanation of how the example works.
• Don’t use code examples to illustrate points that are obvious or scenarios that are contrived.
• Add an introduction to describe the scenario that the code example illustrates and to explain anything that might not be clear from the code. List the requirements and dependencies for using or running the example.
• Design your code for reuse by making it easy for users to determine what to modify. Add comments to explain details, but don't over-comment. Don’t state the obvious.
• Show expected output, either in a separate section after the code example or by using code comments within the code example.
• For code that creates UI, consider accessibility requirements. For example, include alternate text for images.
• Write secure code. For example, always validate user input, never hardcode passwords in code, and use code analysis tools to detect security issues.
• Show exception handling only when it is intrinsic to the example. Do not catch exceptions that are thrown when invalid arguments are passed to parameters.
• Always compile and test your code.
• If you're publishing your content on the Internet, provide an easy way for users to copy and run the code. If the code example demonstrates interactive and animated features, consider providing a way for the user to run the example directly from your content page.
• If you're publishing content on the Internet, use appropriate keywords, linking strategies and other search engine optimization (SEO) techniques to improve the visibility and usability of the code example. For example, add links to relevant code example pages and content pages to improve SEO across your content.

The following are some guidelines for formatting and naming code samples:

• Use white space and indentation to improve the readability of your code.
• Use blank lines to separate individual tasks or components in the code.
• Avoid long lines of code; if possible, break these into multiple lines to improve readability.
• Use a monospace font for all code examples, whether they’re embedded or text or displayed as separate paragraphs.
• If you omit part of an example for clarity or length considerations, insert a comment at the point of omission to explain what should be added to make the code compile, or use an ellipsis (in a comment) to indicate that code segments have been omitted. Identify code that users must edit or add before the code can be compiled. If your documentation will be localized, consider putting this information in the body of the topic as well.
• Observe the casing and coding conventions for the language you are documenting.
• Use fictitious people names, company names, email addresses, and URLs.
• Remember worldwide users. Do not use examples that include U.S.-centric data, such as zip codes or sports teams.
• Do not use sensitive geographic and cultural references.
• Do not use offensive language or slang. For example, do not use foo or bar or their derivatives when naming coding constructs.
• Use descriptive construct names. Do not use names that are too generic or that include the prefix My.

Organize Your Text

Help your users to quickly locate the information that is important to them using clear, well-reasoned content organization. Here are some general guidelines:

• Put the most important content first. Put the most important content in the content’s title, headings, subheadings, and the first sentence of each paragraph.
• Use the inverted pyramid style. Write the key points first by using keywords, so that users will see them and know whether they want to read on. In other words, give the conclusion first.
• Include an overview. When writing procedural documents, it’s important to orient your readers with an overview that will help them see the overall purpose of that section of the document and what they are about to do.
• Use short, focused paragraphs. Avoid complex paragraphs that express more than one idea. State your point in the topic sentence of each paragraph and stick with one idea per each short paragraph.
• Use notes and tips. Your main paragraph should focus on the main point, but you should include notes and tips by breaking these out of the main paragraph. This also helps to give some variety to the monotony of the page.
• Use clear language. Keep your sentences simple and short. Use keywords that users understand and use regularly. Avoid self-serving speech. For example, they want to "download," not to "experience the latest innovations." Also avoid using technical terms and jargon that users may not intuitively understand.

Use a Table of Contents and Headings

If you have a long content set, it's very important to include a Table of Contents (TOC) with links to every subheading. Keep the content of each page short and brief if possible.

Good headings are crucial to helping users navigate easily through your documentation. A few guidelines about headings:

• Make headings and subheadings short.
• Use keywords as your headings.
• For headings introducing tasks, use gerunds (verbs ending in –ing).
• Use nouns or noun concepts for headings that introduce basic concepts or information.
• For headings introducing a guideline or policy, use the imperative voice.
• Only use question style headings in FAQs.

Balance the Need to be Concise Versus Comprehensive

You can shorten nearly everything you write. Short, strong sentences are the essence of good technical content. Streamlined text helps your readers to find what they're looking for--and fast. Clear, simple text is also easier to understand. Readers strongly prefer concise, direct writing.

However, make sure you do not sacrifice your meaning in an effort to be concise. Don’t use a chainsaw to cut down your text when a scalpel would do better. Cut length--not clarity.

Here are a few phrases to look for when trying to find ways to condense your text:

• Words or phrases that add unneeded bulk to a sentence and weaken its message.
• Common phrases that are bloated with redundant words or unnecessary information.
• Unimportant words at the beginning of a sentence that push the most important words farther away from the start.

By the way, don’t omit the word that, especially when it introduces a clause. It's a good word to keep in for clarity.

Use Lots of Links

Using links to related information can help keep your content concise and scannable. The goal of a link is to help users find the information they want, so descriptive link titles are critical.

You should try linking to background and related information rather than summarizing. Also, if you’re creating a large set of content, improve the ease of navigation by including many cross-references.

For more information about how to properly format a hyperlink, see Links.

If you are writing in a print medium, you can provide the reference and page number for the material instead.

Use Lists

When appropriate, use bulleted or numbered lists, which are easy to scan and more likely to be read than paragraphs of text.

A few guidelines to follow:

• If the steps must be done in chronological order, use a numbered list.
• If the order of the information doesn’t matter, use bullet points.
• Phrase steps in the imperative (as commands).
• Put one action in each step.
• If conditions apply to the action, include them in a phrase or dependent clause before the imperative.
• If your lists are too long, consider breaking it up into smaller chunks using headings and/or section breaks.

Chunk the Content

Pay attention to places where you’ve got a large "chunk" or section of information. For example, long blocks of text or paragraphs. Especially long lists can be tedious as well. When you notice this type of problem, try conceptualizing your text differently. Can your content be subdivided in a logical way? Once you’ve subdivided it appropriately, you can break the content up using headings or subheadings. You can perhaps express things in a table, a flowchart, or a figure. You can perhaps break the content up into different pages.

Use White Space

White space refers to the areas on a page that have no text or visuals: the space between lines, in the margins, around visuals, between the visual and its caption, and around titles and headings. Effective use of white space can help users scan the page and more easily identify what they need. Pay attention to the amount of white space between the content “chunks” on your page.

Use your white space to signal relationships between the elements of the page and add emphasis to important items (by increasing the white space around it). White space helps to direct your user's eye to the right spot on the page. You can also use white space to add variety and visual interest to the page.

One helpful way to think about is to think of the idea of the fold on the screen. The term fold refers to the newspaper medium. Back in the days when print newspapers were more common, editors knew they needed to put their most important text above the crease where the newspaper was folded.

In that vein, content that is on the first screen ("above the fold") is more likely to be read; users are unlikely to scroll down to find more information. This means that you need to reduce word count (preferred) or increase the total number of pages (by dividing a page into shorter, separate topics). Remember that where “the fold” is depends on factors that you might not control, such as the device used to view your content and screen resolution.

Select Readable Fonts

From a usability perspective, there are different opinions about whether it is better to use a serif font (like Times New Roman) or sans-serif font (like Arial) for the body text of a document. In the 1990s, researcher Colin Wheildon studied how well readers could comprehend a body of text written in a serif or sans-serif font. He found that 670,000 out of a million readers could fully understand or comprehend the serif font compared to only 120,000 readers who read the sans-serif font.

While the previous study suggests that you should always use a serif font, other studies have shown this isn't always the case. Another study at Carnegie-Mellon University suggested that when readers were reading technical information, the majority of readers preferred the sans-serif font. They stated that the font felt "less intimidating" and more "user friendly." Furthermore, other researchers have found that there are different results when comparing font choices that will be read on a computer screen as opposed to print. They found that it was less taxing on the eyes to read sans-serif font on a computer screen.

Regardless of your font choice, you’ll want to introduce some variety in your font choices in the body of your text. For example, consider using a serif font for body text with a sans-serif font for headings or vice versa. You could also format bold text in a different font style for variety.

NOTE: Please don't embed fonts into your HTML. Use CSS to control your fonts.

Use Appropriate Visuals

Good visuals are essential to effective technical communication. You may have heard the proverb that "a picture is worth a thousand words." In technical communication, a good picture can replace a thousand words of explanation.

Although you don’t want to overuse or misuse visuals, it's a good idea to use them liberally. Feel free to use screenshots, possibly with the use of arrows or other callouts to highlight important parts of the screen. Animated gifs can also be effective for demonstrating an action. Sometimes a video that demonstrates what you are trying to illustrate can be very powerful.

If You Do Only Six Things

The following guidelines come from the Microsoft Manual of Style, 4th edition. Microsoft outlines six bare minimum requirements for creating effective user interface text:

1. Start writing UI text early, because UI text problems often reveal product problems.
2. Think like a customer and ensure that you understand the entire workflow process:
• How do customers get to this surface?
• What is the essential information that they need to accomplish the task on this surface?
• Where are they going from here?
3. Design your text for scanning.
4. Be concise, eliminate redundant text, and don't over-communicate. Too much text discourages reading.
5. Provide links to Help content for more detailed information only when necessary. Don’t rely on Help content to solve a UI problem.
6. Use a consistent voice and consistent terminology across the product or service.

High-Level UI Checklist

This checklist comes from the Microsoft Manual of Style, 4th edition:

• Is the text that describes the flow to and from the given UI surface logical?
• Is the point of the UI surface clear?
• Did you provide enough information for users to make a smart decision? Can they scan the text and still be successful?
• Did you use plain, straightforward words that your audience will understand?
• Did you use the terms consistently? Is the voice consistent?
• Could you use fewer words while still ensuring that the customer will succeed?
• Is the UI text easy to localize? Will the text still work with the visual design if the text were to be 30 percent longer after translation?
• Does the text inspire users' confidence that they can complete the task at hand?

Consult the FlexSim Technical Writer

The FlexSim technical writer should ideally be someone who has a good range of vocabulary and a sense of how to phrase things in a way that is intuitive and easy to understand. Consider inviting the FlexSim technical writer to provide feedback about UI text early on in the process.

Design a Usability Test

A usability test is a test that researchers run to determine the user-friendliness of a particular software product. It generally involves giving users a version of a software product and asking them to perform a series of activities using the software. It can also be used for testing whether technical documents (like user manuals) are easy to use.

Usability tests are incredibly valuable for both software and technical document design. Although it may seem like common sense to have users test a draft of a document or software before releasing it to the public, many organizations do not do so, resulting in documentation or software design that is frustrating and alienating to use. Fortunately, usability tests are inexpensive to create and can provide significantly useful data about how to improve a product. From a cost-benefit perspective, usability tests just make good sense.

Usability tests can possibly be conducted a number of different ways:

• You can observe an individual attempting to use the software or the document. This observation can be done in person or it can be recorded.
• You can interview an individual about their experiences using the software.
• Some companies use software that analyzes keystrokes and mouse positions. Some companies also use heat sensors to track the parts of the screen users look at the most. These tools can sometimes reveal tasks that are difficult for users. There are many free or open source versions of this software.

Indicative Mood

The indicative mood expressed information such as facts, questions, assertions, or explanations. In technical writing, the indicative mood should predominate, except in procedures. The following are examples of sentences in the indicative mood:

• FlexSim software products can help you identify places where your production line could be more efficient.
• You can import a CAD drawing of your health care facility into FlexSim Healthcare to make your model more precise.

Imperative Mood

The imperative mood expresses requests or commands. You should use the imperative mood when writing procedures and direct instructions. In the imperative mood, the subject is always you, but the "you" might sometimes be implied. The imperative mood is always in the present tense. A few examples of the imperative mood:

• Click Reset and Run to start the simulation.
• Select the Use Transport check box.

Subjunctive Mood

The subjunctive mood expresses wishes, hypotheses, and conditions contrary to fact. The most common use of the subjunctive mood is to express a recommendation or to insist on something. You should generally avoid using the subjunctive mood in technical communication. The following are some examples of the subjunctive mood:

• We recommend that you be careful about opening email attachments.
• If you were to save your project regularly, it would help prevent data loss.