Correct spelling and typographical errors throughout the text.
Correct spelling and typographical errors
Add citations to Clause 1.2 and a reference page.
Add citations and a reference page.
do not use 'above', rather list a section #
Provide explicit location reference.
Rearrange redundant information in Introduction.
1st paragraph of Clause 1.4 deleted, and its content revised and included in Clause 1.3
Sub-clause references should be '7.3.3' and '7.18'
Corrected sub-clause reference from '80' to 7.18' and from '7.31' to '7.3.3'.
Separate headings from other text.
Separate headings from other text
Change 'graphs' to 'paths' in 7.7.
Change 'graph' to 'paths'.
Replace long lists.
Make tables of lists where appropriate.
Delete roles and edit 7.4.2 text. No other changes.
Indicate that the popular concept of code 'smells' is synonymous with weaknesses in this specification.
Address 'smells' as a Note to entry in the Clause 4 under Weakness definition.
Replace '>' throughout with '>'
Replace '>' with '>'.
Include Pi and summation in Symbols clause 5
Add symbols to Clause 5
Rework presentation of process steps
Section 7 process description
The computational processes are currently described in Subclause 7.1 and presented in Figures 2 and 3.
Illustrate how to make best use of TD measures: vis-à-vis actual organization's objectives as opposed to vis-à-vis ideal no defect situation.
Expected benefits: more palatable values for non-technical audiences.
Proposed content
<<<
8.5 Technical Debt value communication
The following scenarios illustrate ways in which the Automated Technical Debt Measure (ATDM) and the Contextual Technical Debt Measure (CTDM) can be used to help communicate about Technical Debt with non-technical audiences, facilitate acceptance, and reap the benefits of the Technical Debt metaphor.
8.5.1 Problem statement
ATDM and CTDM are estimating the effort to remove all occurrences of the selected patterns (from ASCSM, ASCRM, ASCPEM, ASCMM specifications, or from a user-defined list).
First, this is equivalent to a strategy of zero tolerance to defects which may be too stringent (and very likely unnecessary) to implement to all applications, as well as too expensive due to the sheer number of occurrences to remove. This leads to remediation effort values so large they are difficult to accept (even if justifiable), ultimately creating a push back against the whole measurement program.
Second, there is conceptual debate about the content of Technical Debt. Some says Technical Debt should only account for items that organizations have the intention to remove at some point in time. In other words, if organizations do not plan to completely remove all occurrences of each pattern, they are not to be considered in the Technical Debt measurement.
Third, some organizations manage quality objectives, such as internal or external Service Level Agreements. That is, they define some requirements on the number of issues that are considered acceptable. In this context, when quality objectives are set with a certain tolerance value, it means that only the occurrences whose removal is needed to reach the target level of tolerance will be effectively removed; the remaining occurrences will remain for lack of incentive to do so. In these frequent situations, the Technical Debt values that are meaningful for the management are the estimations of the effort and cost to reach target values (as opposed to the estimation of the effort and cost to get the total absence of occurrences).
8.5.2 Recommended approach
8.5.2.1 When quality objectives are set
CISQ recommends the computation of the amount of Automated Technical Debt Measure that is required to reach quality objectives that are set for each application.
As the scope of the measure is adjusted with contextual information, this computation should be exposed as a Contextual Technical Debt Measure to avoid confusion.
The immediate benefits of such approach are:
a more relevant value,
because it would be aligned with organization’s existing management practices, as opposed to a value relative to an hypothetical “zero tolerance” situation;
a more acceptable value,
because it would be smaller, having filtered out effort and cost amounts that are not ultimately applicable
8.5.2.1 When quality objectives are not set
In case there are no quality objectives set, CISQ recommends the computation of the amount of Automated Technical Debt Measure required to reach arbitrary yet meaningful quality levels (such as the sigma levels).
The immediate benefits are:
a perspective on quality levels,
especially as there are no objectives set, to educate and help justify quality improvement initiatives (e.g., showing that there is an effort to plan to reach a sigma 3 level can resonate with non-technical management audience familiar with these concepts)
a more acceptable value,
because it would be smaller, having considered the removal of some occurrences only, (removing all occurrences would be completely unrealistic when dealing with an application for which there are no objectives set).
8.5.3 Limitations
Benchmarking
The adjustments regarding the tolerance are incorporated at the expense of benchmarking, which cannot be accomplished with CTDM except among applications where the CTDM adjustments are identical or acceptably different.
“Acceptably different” means there are differences in the adjustment criteria but that the organization is accepting and adhering to these differences and their impact on the way to interpret the results.
As an example, if two applications are assigned different tolerance levels, the organization must use the CTDM measures knowingly: the measured values shall not be used to compare the Technical Debt for these two applications but they shall be used to compare the distance to their respective quality objectives, using a Technical Debt metaphor.
Value range
As soon as the tolerance level is not zero, this means that some occurrences will have to be removed and some occurrences will be allowed to remain.
Each of the candidate occurrence for any given pattern leads to the same unadjusted remediation effort. However, as soon as the adjustment factors kick in, the adjusted remediation effort will very likely differ.
Therefore, the effort required to remove enough occurrences to reach the quality objective for this pattern becomes a value range, with a minimum value obtained by targeting the occurrences with the smaller adjusted remediation effort values, and with a maximum value obtained by targeting the occurrences with the largest adjusted remediation effort values. Obviously, to keep using a single value, the median or the mean value can be used.
>>>
Old 8.5 should be improved to explain use of the TD measure
Improve 8.5 with more explanatory material.
§ Predictive model sub-clause used to detail adjustment factors.
Adjustment factors are now part of the normative section of the document
Alternative adjustment factors formula (that is, formula different from the standard one specified in the normative section) as well as additional adjustment factors (e.g., Evolution Status) can be moved to § Calculating a Contextual Technical Debt (CTDM) sub-clause
Proposition to
1/ remove the § Predictive model sub-clause
2/ move alternative adjustment factors formula as well as additional adjustment factors to § Calculating a Contextual Technical Debt (CTDM) sub-clause
From
<<<
The Contextual Technical Debt Measure (CTDM) is an alternative to the Automated Technical Debt Measure, because it is adapted to the context of a specific organization or application. The adaptation process is multifaceted and concerns one or more of the following aspects:
the list of patterns to consider: a subset of the patterns from ASCMM, ASCRM, ASCPEM, and ASCSM; or a set including source code patterns not included in these Quality Characteristic measures.
different values for remediation effort: different Remediation Effort formulas, different Remediation Effort unit values, etc.
the use of adjustment factors, as illustrated in previous sub-clause
the evolution of the configuration over time.
However, these adjustments are incorporated at the expense of benchmarking, which cannot be accomplished with CTDM except among applications where the CTDM adjustments are identical.
>>>
To
<<<
The Contextual Technical Debt Measure (CTDM) is an alternative to the Automated Technical Debt Measure, because it is adapted to the context of a specific organization or application. The adaptation process is multifaceted and concerns one or more of the following non mutually exclusive aspects:
the list of patterns to consider: a subset of the patterns from ASCMM, ASCRM, ASCPEM, and ASCSM; or a set including source code patterns not included in these Quality Characteristic measures.
different values for remediation effort: different unadjusted Remediation Effort formulas, different unadjusted Remediation Effort values,
the use of different formulas for adjustment factors, or their deactivation
the use of additional adjustment factors
However, these adjustments are incorporated at the expense of benchmarking, which cannot be accomplished with CTDM except among applications where the CTDM adjustments are identical.
The following sub-sub-clauses illustrates sample variations regarding adjustment factors.
8.4.1 Technological Diversity
Principle
Adjust the Technological Diversity adjustment factor to better reflect the organization’s ability to deal with occurrences involving multiple technologies.
Illustrations
Turn off (that is, ignore from computation) the Technological Diversity adjustment factor if the organization is organized around cross-technology teams.
Compute an alternative technological diversity penalty factor equal to the power of the number of distinct technologies, with a power value smaller than 1, to model a smooth coordination of different teams, and greater than 1, to model the infrequent involvement of different teams.
8.4.2 Exposure
Principle
Adjust the Exposure adjustment factor to better reflect the organization’s ability to avoid destabilization of the software via automated testing.
Illustrations
Turn off (that is, ignore from computation) the Exposure adjustment factor if the organization is so mature regarding automated non-regression testing that teams can update the code without fear of side effects
Compute an alternative exposure adjustment factor using one of the following formulas:
with an asymptote: max-1/(range number+1)power
without an asymptote: (range number)power
where range number is a logarithmic transformation of the exposure values, to account for combinatorial nature of the exposure and make them human-friendly: |log (exposure + 1)|
8.4.3 Concentration
Principle
Adjust the Concentration adjustment factor to better reflect the organization’s strategy regarding the removal of Technical Debt occurrences.
Illustration
Turn off (that is, ignore from computation) the Concentration adjustment factor if the organization is willing to remove occurrences one at a time, that is, without considerations about other occurrences involving the same code elements.
8.4.4 Evolution Status
8.4.4.1 Occurrence
Principle
Adjust the remediation effort for a Technical Debt Item with an evolution qualification measure to factor in the opportunity to remove an occurrence more easily when it was injected into the software during the current release cycle.
Illustration
Consider an occurrence evolution reward factor of .50 for added occurrences.
8.4.4.2 Code elements
Principle
Adjust the remediation effort for a Technical Debt Item with an evolution qualification measure to factor in the opportunity to remove an occurrence more easily when the code elements involved were recently updated.
Illustration
Consider a code element evolution reward factor of .75 for updated code elements.
8.4.4.3 Limitation
Please note that the use of such adjustment factors makes the measures evolve over time, even if the software is not evolved in any way, as the occurrences “grow old” and the opportunity to remove them more easily vanishes.
>>>
Old 8.4 misaligned and should be replaced with a section for calculating CTDM which is a non-normative measure referenced in section 6.
Provide a better description of CTDM for readers to use in implementing CTDM measures.