Courses: Introduction to GoldSim:

Unit 15 - Documenting Your Model

Lesson 1 - Unit 15 Overview

"A mathematical theory is not to be considered complete until you have made it so clear that you can explain it to the first man you meet on the street."

- David Hilbert

In the previous Units we discussed the technical details of building and running probabilistic, dynamic simulations in GoldSim. In this Unit, we are going to discuss something that is of equal or greater importance: how to properly document your model.

Because adding documentation to a model and making it easier to understand is not “technical”, it is often not considered to be essential, and hence is ignored or put off to the very last minute.  As a result, for many modeling projects, it never gets done at all.  This is a very serious mistake.  Properly documenting your model is critical for three important reasons:

  • Many models have a long lifetime. As a result, you will often need to revisit and make modifications to a model many months (or years) after you last used it. If the model is not well documented, you will need to waste time coming back up to speed with the model in order to understand it well enough to use the model and make any modifications that are necessary.
  • Many models are either built by multiple people, or pass from one person to another over time. In order for others who need to work on the model to do so effectively, it must be well documented.
  • Most models that you build are actually built for someone else (a manager, a client, a regulator, some other stakeholder). Although it may not be necessary for them to understand all of the technical details of a model in order to use it (and we will discuss this further in Unit 16), in most cases it is necessary for them to understand the basics of what the model is doing. A model that cannot be easily understood is a model that will not be used or believed.  A well-documented model can help these stakeholders to better understand it.

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. This Unit describes how to use these important features.

In particular, this Unit discusses the following:

  • Organizing your model;
  • Adding graphics and text to your model;
  • Aligning, spacing, ordering and grouping objects in the graphics pane;
  • Creating Notes;
  • Adding Hyperlinks to the graphics pane;
  • Customizing the appearance of elements;
  • Modifying and filtering influences; and
  • Using clones to better organize a model.

This Unit has a total of 10 Lessons (including this overview and a summary at the end). The Unit does not include any Exercises, but does include several Examples that we will explore.  Moreover, as a new feature is introduced, you will be encouraged to use it and experiment with it.  This Unit is conceptually much simpler than the previous Units, so it should not take very long to complete.