Courses: Introduction to GoldSim:

Unit 15 - Documenting Your Model

Lesson 10 - Unit 15 Summary

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. Documenting and organizing your model is important: a model which cannot be easily understood is a model that will not be used or believed.

This Unit described how to use these important features.

In particular, the key points that we covered were as follows:

  • The most important way to ensure that your model is easy to explain and understand is to spend some time to organize your model. For a model to be successful (i.e., useful), you must be able to present and explain your model effectively to all of these audiences. The primary way in which you accomplish this is by organizing your model into a logical, top-down hierarchy. Containers provide the mechanism in GoldSim by which you can create well-organized, hierarchical models. In most cases, you do this by placing model elements in a “top-down” containment hierarchy in which the level of detail increases as you "push down" into the hierarchy.
  • One of the most powerful ways to document your model is to use GoldSim’s features for adding graphics (an image of a simple schematic) and text to the graphics pane. The Drawing Tools toolbar in GoldSim provides access to buttons for adding images, graphics, text and Text Boxes to your model. 
  • One of the simplest (but still highly effective) things you can do to “clean up” the appearance of a model, and hence make it easier to understand, is to align and space the elements (and graphic objects) in the graphics pane. GoldSim provides standard tools for aligning, spacing, ordering and (for graphical objects) grouping items in the graphics pane.
  • The Description field for an element provides one (of several) mechanisms for you to properly document your model.  However, the length of the Description field is limited (it is meant for a line or two). In some cases, you may want to associate a significant amount of text with an element.  GoldSim supports this by allowing you to attach a Note to an element.
  • Hyperlinks to other documents (e.g., web pages, PDF documents, etc.) can be inserted within Text Boxes and Notes.  This provides a very powerful way to document your models. In addition to these two methods, GoldSim provides a third way to add a hyperlink: you can add one directly to the graphics pane via a Hyperlink object. Not only can you use this to jump to websites and documents, you can also use it to navigate your model (by providing a link that “jumps” to another part of the model).
  • GoldSim provides the ability to customize the symbol that is used in the graphics pane to represent an element.  This is most commonly done for Containers. Because Containers often represent sub-systems of the model, customizing their symbol to better represent what is actually being represented inside the Container can make the model easier to understand. 
  • When you link one element to another, GoldSim automatically draws an arrow (referred to as an influence) between the elements. The influence visually indicates the dependency of one element on another.  GoldSim allows you to modify the appearance of influences (e.g., changing their color and/or thickness; adding a label).  You can also choose to hide them completely. Under certain circumstances, this can improve the appearance of your model and make it easier to understand.
  • When you create clones of an element, all of the clones behave identically: if you change one of the inputs to a clone, the same input is automatically changed for all of the other clones. Cloning can be used to better organize models and make them easier to understand.

Although GoldSim provides powerful tools for documenting and organizing your models, you still must take the time to use them.  If you wait until after you model is built, it is highly unlikely that your model will be properly documented. Models should continuously be documented and (re)organized as they are built.

Note: The GoldSim Model Library is a collection of models on the GoldSim website. By browsing through the Model Library and viewing the various models, you can view examples of how to document and organize a model.  We will discuss the Model Library in more detail in Unit 17.