In this article, we will describe the reasons why you may want to consider documenting your models and what to document if you choose to do so.
Tracking Quality Metrics for Model Quality Improvements Over Time
If model quality is one of the requirements of your project, you’ll need to track proper quality metrics over time.
Quality metrics such as
- the cyclomatic complexity,
- the number of bugs,
- the implementation’s locations of the requirements,
- a list of the requirements not yet implemented,
- the number of parameters used in the model,
give you an estimation of the quality of your models. Likewise, having an answer to the following questions can prevent a lot of quality issues:
- Can you generate embedded code from your model?
- Are the libraries inside your model properly linked?
- Can your model run?
- Does your model contain blocks with an undesired configuration?
- What are the output and input signal data types and range of variations?
Using the Metrics
Using the metrics described above, you can know how much work is needed for a particular model if you want to improve its quality. Documenting these pieces of information can help with several important tasks among which the following:
Filtering Out the Noise
Assembling critical information in a single document is paramount when you need a quick overview of the status of all potentially critical items. Having one document where all the cumbersome information is filtered is essential if you have items that are critical in the development of your project (e.g. if you are using referenced models inside a top-level model, it may be critical that both the top-level model as well as every referenced model run independently). Note that the top-level model could run with one of the models not running if a parameter is initialized by different referenced model for example.
Identifying Regression in Your Model Early
If you are able to track a specific metric on a regularly basis, you’ll be able to identify unexpected regressions of your model when that metric varies in an unusual way. You don’t even have to understand what that metric means to notice that it’s unusual, the investigation can come later. For example, if you see that the cyclomatic complexity of your model doubled in a short amount of time, you may want to investigate, as it may hide a deeper issue.
Allowing Better Model Inconsistencies Identification
When documentation is available you don’t need people to know your code to get involved with your project. This makes it possible for them to review and identify inconsistencies within your code (provided that your documentation actually reflects your implementation which we’ll see how to do in another article). For example, if requirements are coded in a wrong location in your model, it can be noticed from the documentation.
Identifying issues early prevents the accumulation of small modification needed at the last minute, i.e. when you can’t afford it. You don’t need to correct every issue as they arise. In fact, you could even save time by batching together small corrections to tackle when you feel like you’ve accumulated enough small mistakes to perform the corrections. Whether batching your modifications is a good approach is really up to you and depends on your situation. The point is that in order to have control over this, you need to document it.
Making Extrapolation and Time Frame Estimation Possible
When the documentation of your metrics is up to date, you can measure the pace of improvement and extrapolate to know whether you will attain your goal within an acceptable time frame.
Preventing Interface Issue
Documenting the interfaces of your models (i.e. the range of variation and data type of your inputs and outputs) provides information for the model receiving those signals. When coding this model, you then know what to expect and can use the information accordingly. This part is critical if you want consistency between every part of your model. Doing this for your top-level models ensures they will interact the right way with each other. For example, if an output signal contains the state of a variable in your model (e.g. 0: not activated, 1: partially activated, 2: completely activated) you’ll want to make sure every value of this signal is used appropriately.
