18. Annotations¶
MQC provides the possibility to annotate the quality of the quality properties and artifacts in your project. This functionality allows you to add a description to justify the observed quality for a duration of your project. This description/comment allows other users to know why a certain quality property might be performing poorly. In this way the justification is documented in a more transparent way.
MQC objectively calculates the quality of your project. This can be configured in Quality Model, Project Structure, Target Values, and Context Categories, etc.
For special, real-world cases you could use annotations to document derivations from expected values. Additionally, you can use annotations to change the quality value or bin if they need to be treated differently than the one calculated.
Use annotations sparingly to describe or justify the quality of certain quality properties and artifacts. Modify the quality value or bin only if necessary.
18.1. Configuration of Annotations¶
To configure annotations go to the Data Management Panel and select Annotations. This opens the Annotations dialog.
Here you can see the drop-down menu with all the artifacts that are currently
present in your project. The left-hand side of the menu displays the name of
the artifact. The right-hand side shows the number of annotations defined for
this artifact. Here 0 (0) Annotations
informs you that there are 0 active
annotations and (0) unmatched annotation. In Annotation dialog after annotation is added.
you can see an example of 2 active and 1 unmatched annotation.
An unmatched annotation is one which does not match the project timeline, artifacts, quality properties or bins that are currenlty defined.
Select the artifact to list the quality properties of your project. Here you can easily view and edit the annotations associated with each artifact and its respective quality properties.
Each quality property itself is a drop-down list showing the enabled
or disabled annotations and No Annotations
if none are defined.
To add a new annotation select Add Annotation
at the top right of the
dialog.
The following fields are available to define an annotation.
Artifacts: (mandatory) Select one or more artifacts this annotation should be applied to. The drop-down menu restricts you to the artifacts present in your project.
Quality Properties: (mandatory) Select one or more quality properties this annotation should be applied to. The drop-down menu restricts you to the quality properties defined in the quality model.
Short Description: (mandatory) Add a caption or a title to identify the annotation easily or to provide a quick overview of the annotation.
Long Description: (optional) Here you can add a more detailed justification or description of the annotation.
Valid From: (optional) Select the start date in the calendar from which the annotation is active. If left empty MQC treats the annotation as active from the start date of the project.
Valid To: (optional) Select the end date until which the annotation is active. If left empty MQC treats the annotation as active until the end date of the project.
Condition: Define the qualifying condition based on which the underlying quality value or bin would be changed. The first drop-down menu allows you to select the type of condition. By default the condition is set to
Bin
. The field below selects the bins defined in your project for which the annotation must be active. If you selectQuality
as the condition type you will see a range selection bar. Here you can select the range of quality for which the annotation must be active.Target: Define the target quality value or bin you would like to annotate when the condition defined above is true. By default the target type is set to
Bin
and you can select only one target quality bin. If you selectQuality
in the drop-down menu you can change the target quality value with the slider or edit the field directly.Disabled: Enable or disable an annotation. Disabled annotations are not applied but remain in the project and can be enabled at any point in time.
You can use different combinations of qualifying conditions and desired target values for an annotation. For example:
If you want to change a quality bin from Bad to Acceptable, set the Condition type to Bin and select the quality bin
Bad
. Then set the Target type to Bin and select the quality binAcceptable
.If a quality bin is too broad you could use the Quality condition instead. Set the Condition type to Quality and select a range between
10
to15
. Then set the Target type to Bin and select the quality binAcceptable
.If the target bin makes the quality too high and you would like to specify it directly, then set the Target type to Quality and the quality value to
25
.Finally, you can also define the condition as bin and target as value. Set the Condition type to Bin and select the quality bin
Bad
. Then set the Target type to Quality and the quality value to25
.
Note
If the target is a bin then the underlying quality value is also changed and vice versa. The respective values are chosen from the bin configuration defined in the quality model.
Once the annotations are added, they can be seen in the annotation dialog.
If any field is invalid it is marked in red, the annotation is grayed out,
and the annotation cannot be applied to the project.
For example, the Valid From
or Valid To
dates are outside the timeline
of the project.
If you had already marked certain artifacts, quality properties from the KPIs
or an element from the main visualization, they are pre-selected respectively
in the Annotations
dialog as well as in the Add Annotation
dialog.
If you would like to remove this pre-selection simply uncheck the
Respect Marking
check box at the top of the Annotations dialog.
Once the annotation is added you can also edit, disable or delete it on the right-hand side of each annotation.
Note
When an annotation is disabled it stays in your project. It can be enabled at any point in time.
In contrast to disabling, deleting an annotation completely removes it from the project.
The Edit Annotation dialog is the same as the Add Annotation except for
additional fields: the creation date, the modification date, and the author
of the annotation. Select Update
to save the changes.
If you have made any changes, that is, added, edited, enabled, disabled
or deleted annotations select Save
to apply these changes to your project.
If the Apply to Quality
annotation setting from the settings dialog is
enabled all the changes will be visible in your project.
18.2. Import and Export of Annotations¶
MQC provides the possibility to import as well as export annotations to/from your project.
Click on the Export Annotations
button at the bottom of the annotation
dialog to create a yml file containing all the annotations defined in your
project.
The annotations are structured hierarchically as per artifacts and quality
properties. Only the fields that were defined for the respective annotation are
present in the export.
The same exported file can now at any point be imported again by clicking on
the Import Annotations
button. The import button could also be used to
import annotations that are common for multiple projects. Thus the import
functionality also allows you to import annotations with undefined mandatory
fields or fields defined out of the project scope like artifacts,
quality properties, dates, etc. Such annotations are considered invalid.
You can now edit these invalid annotations to make it applicable to your
current project.
Note
Importing annotations replaces the existing annotations in your project.
So that at all times times the different configurations made in the Quality Model and Project Structures, namely, measurement functions (see Measurement function definition), target values (see Target Values), context categories (see Context Categories), etc. is strictly followed by MQC. This ensures that once the configuration changes are made at one place the user does not need to be involved in any way to calculate or manipulate the quality that is seen on the dashboard and different pages of MQC and provides transparency.