Documentation

This article is part of the GoldSim Style Guide. For an introduction, please start here.

A model which cannot be easily explained is a model that will not be used or believed. As a result, GoldSim was specifically designed to allow you to effectively document, explain and present your model. You can add graphics, explanatory text, notes and hyperlinks to your model, and organize it in a hierarchical manner such that it can be presented at an appropriate level of detail to multiple target audiences.

The most important way to ensure that your model is easy to explain and present is to spend some time to organize your model. Use the ideas presented in the previous sections to better organize your model.

The goal for documenting a GoldSim model should be to provide all documentation needed for the reader to understand the model without having to refer to an external document. It’s expected that you might need to refer to external documentation of any well-established functions used in the model, which provides some needed context.

Display Units

It should be decided at the start what units are used for various types of calculations in the model. You should avoid building a model with a mix of display units. For example, half of all flow type elements have display units of ML/week and the other half uses m3/d for no apparent reason other than one person had a different preference at the time or because nothing was decided. The result of this is that you must change a lot of display units in various elements or charts to maintain consistency throughout the model.

Text Blocks

GoldSim provides two ways to add text to the graphics pane:

• Text object
• Text Box

Text objects are movable objects that can utilize a single font.  Text Boxes are scrollable boxes of text that can simultaneously utilize multiple fonts and can be “pinned” to a specific location in the graphics pane. We recommend that you use Text objects unless a special formatting is needed like hyperlinks, sub/super scripts, bold sections, etc.

Use the default font for text in the graphics pane except for headings. The default font is Calibri 11.

Make the bounding box large enough to allow the text to grow if viewed on a screen with different resolution or different zoom scale. The rule of thumb is to provide an extra line of text.

Element Descriptions

Use the Description field for all elements in the model, including Dashboards and Results. Because the Description is displayed in tool-tips, it can be an effective and highly visible documentation tool.

Start with a capital letter on the first word of the description. Try to contain the description within the 2 lines provided. If you need more space, abbreviate then put a more descriptive version in the note pane.

Container Heading

Every Container in your model should have a title. Put a heading at the top left corner of the graphics pane of every Container, written in plain text using Calibri bold, font size 16. Make sure the text block is moved to the top-left corner of the graphics pane.

Container Description

Every container should have a short description located at the top, just under the heading. Omitting text here leaves the reader with the task of opening elements just to figure out what is happening. Add a short paragraph just below the header to provide a basic description of what is being done in this container. Make sure the text block is moved to the top-left corner of the graphics pane, just below the heading. It is recommended that you keep the width of the text block to less than 8 inches.

For reference, the font settings for all plain text in GoldSim should have the settings shown in the properties dialog below.

Because text is rendered differently depending on the resolution and Windows screen scaling, you should provide some extra room for the text to grow within the box. The screen capture below shows the same text but with the text border turned on so you can see how much extra space is provided.

If more space is needed to further describe what is happening in the container, consider adding a child Container for more documentation. Alternatively, you can add more text at the bottom of the graphics pane below the elements. You should avoid adding a wall of text that requires the reader to scroll down the page to find the model elements.

Section Borders

Use a plain text block to draw a bounding box around parts of your model. Turn on the text box outline to show the box. Do this by adding plain text and changing the outline to have a color.

The result is a single object that shows a box along with the heading:

Hyperlinks

You can use the Hyperlinks to provide navigation aids for your model.  The Hyperlink can be used to provide links “jumps” to specified Containers, Dashboards or elements from any location. The links shown in the screen capture below are using image files as a background to make them look like buttons.

Notes

We recommend that you add notes to any elements where two lines in the description field is not enough. In order to internally document your model, GoldSim allows you to attach a Note to each element:

An element with an attached note has its ID underlined (and by default the text is blue). You can modify this so that the ID is shown in the defined text color (black by default) via an option on the General tab of the Options dialog (accessed by selecting Model|Options from the main GoldSim menu).

One of the most powerful features of Notes is that you can insert hyperlinks to other documents:

• To insert a link to a URL which starts with "www", you need only type in the address (e.g., www.goldsim.com).
• To insert a link to a URL which does not start with "www", you must specify the transfer protocol (e.g., http://website.com/).
• To insert a link to an ftp site, you need only type in the address (e.g., ftp.asite.com).
• To insert a link that launches an email, you must type “mailto:” before the email address (e.g., mailto:name@company,com).
• To insert a link to some other document (e.g., a Word document or a PowerPoint presentation), you must type "file://" before the document name the full or relative path. Excluding the path points to the current directory of the model file.

When you are entering a hyperlink, GoldSim recognizes it as a link as soon as it sees a space (it will become underlined and the text will become blue). As a result, when you are entering the text, there cannot be any spaces in the link. If the filename includes a space, you can represent this by using the characters %20 to represent the space.  For example, if the filename you wanted to link to was “this file.pdf”, the link in the Note pane would need to look like this:

When you click on a hyperlink in a note, GoldSim will immediately open the application associated with the link (e.g., Internet Explorer, Word).

Influence Line Labels

For some complex relationships among elements, you can add labels to influence lines. Influence line labels are particularly useful for describing the inflows and outflows driving Cell Pathway mass transport.

You can add text to an influence by right-clicking on the influence and selecting Add Label from the context menu, or Shft+double-clicking on the influence (double-clicking on the influence while pressing the Shft key). This will add a textbox to the influence with the word "Text" inside (which you can subsequently replace with your own text).

Keep in mind that if you move elements (and their associated influences) to a different container then the labels will be lost.

Simulation Information

Provide the name of the main author or the organization in charge of building the model along with a short description of the model in the Information tab of the Simulation Settings.

The model author is automatically displayed in the run log. You can also choose to show this and the description in the footer of a result chart.

NEXT -->