Analytica model style guide

The design of Analytica, including influence diagrams and structured model documentation, encourage building models that are much more transparent than other modeling environments, especially spreadsheets. Even so, there are things you can do to improve or destroy transparency with Analytica or any modeling tool! These guidelines help you maintain transparency in Analytica, and other environments too.

Descriptions

Clear descriptions make a model much easier to understand for reviewers, maintainers, and even the person who originally wrote the model a few months later. It is really helpful to include a brief description with every variable, module, and function.

Descriptions for user inputs and outputs

It is especially important to include descriptions for each user input and output, if your model has a user interface for end users. Your end users might not find the title of each object to be sufficient to explain the meaning of each variable, even if it's obvious to you, the model author. The user can see the description of each variable, user input or output, and even module in a balloon bubble, simply by moving the cursor over that element. This works the same in Analytica on the desktop as in Analytica Cloud Player.

Use imperative voice for user inputs and buttons

It's shorter and clearer to use imperative voice:

- Click this button to see the result

Not: The user should click this button to see the result.

Also, use second person "you" or "your" as appropriate.

Select the state in which you live.

Not: The user must select the US state in which he or she lives.

For a checkbox:

Check box to include the results in the saved file.

Not: The user should check this box if he or she wants results to be included in the saved file.

Descriptions for other variables

Descriptions for variables should start with a clear description of what the variable represents. It's a good idea to expand any abbreviations that are not very widely known in this domain. It's often simplest to start with a noun phrase. No need to say "This variable is..." or "This represents ....":

If the Definition is complicated, it may be helpful to add a brief overview of what the calculation is doing at the end of the Description.

Fill out Units

It is very helpful to include Units for each variable. If it has no units (dimensionless), it's better to put "-" or "none" in the units than to leave it blank, so readers knows it has no units, and you didn't just forget to enter them.

Error messages

Error messages are the most horribly written part of most software (perhaps second only to the license agreement).

= Don't embed numbers in definitions

Don't embed numbers, like conversion constants, in definitions. Instead define a Constant to contain the number, and use the Constant in any Definition that uses it. For example, avoid:

Variable