Standardize inputs and measures across sub-controls

[adammontville]

Problem

In the specification, each Sub-Control contains a set of Inputs and a set of Measures. Inputs are presented as ordered lists, so that the specification can reference them as "Input x". Measures are denoted as Mx, where x is a positive integer. Input and measure labels are effectively reset for each Sub-Control. For example, the input ordered list at the beginning of each Sub-Control resets to begin numbering at 1, and M1 exists across all Sub-Controls. In the case of the measures, more often than not similarly labeled measures carry different meaning.

From time to time, the same inputs and measures may be used across Sub-Controls. For example:

• Sub-Control 3.1 includes the following measure: M3 = Count of endpoints (from Input 1), where Input 1 is the "List of endpoints"
• Sub-Control 4.8 includes the following measure: M7 = Count of endpoints from Input 1, where Input 1 is the "Endpoint Inventory"

In the above example, the inputs for Sub-Controls 3.1 and 4.8 are synonymous, but clearly not expressed using the same language. While "list of endpoints" is intended to be equivalent to "endpoint inventory", the specification needs to use the same language.

It then follows that M3 of Sub-Control 3.1 and M7 of Sub-Control 4.8 are clearly the same measure.

The fact that same inputs and same measures are referenced differently across Sub-Controls makes implementation more challenging.

Proposal

The specification may benefit from standardizing inputs and measures across Sub-Controls using variables.

Input variables may be denoted by Ix, where x is a positive integer starting with 1 for the first input of the first Sub-Control, and will be incremented by one for each new input across Sub-Controls.

Measure variables may be denoted by Mx where x is a positive integer starting with 1 for the first measure of the first Sub-Control, and will be incremented by one for each new measure across Sub-Controls.

[apiperCIS]

That is a good summary of the problem at hand. For the proposal, I would recommend the following:

1. Use a notation such as GM1, GM2, etc. and GI1, GI2, etc. to represent global measures and global inputs.
2. Local measures and local inputs would just be represented with M1, M2, etc. and I1, I2, etc.
3. The local measures and inputs would be numbered independently by Sub-Control rather than continuously across Sub-Controls.
4. If a change results in a missing entry for a measure or for an input, that is fine. I do not think we should renumber the remaining measures or inputs. For instance, if a Sub-Control has measures M1 through M4 and we convert M1 into a global measure (let's say GM6), then the resulting list of measures would be GM6, M2, M3, and M4. Later, if we decide that M3 is unnecessary, the list would be GM6, M2, and M4.

The rationale for these suggestions:

1. Numbering continuously across Sub-Controls would mean that changes to earlier Sub-Controls would ripple through all the later Sub-Controls causing a great deal of renumbering (for example if we added or removed a measure from Sub-Control 2.2). Or, future versions where we added a measure might have numbering like M1, M2, M878.
2. Keeping the existing M1, M2, etc. for non-global measures would result in fewer changes. This is both a time-saving measure, and to reduce errors. Changing the name of a measure results in many manual changes since measures are often referenced by operations, other measures, metrics, etc. Changing all of these references manually will be an error prone process and should be kept to a minimum; only those changes that really add value should be undertaken.
3. The time-saving and minimizing changes argument in 2) also applies to not updating the numbering due to missing measures and inputs (if we remove some or make a measure a global measure for instance).

Ideally we would have a document writing system that uses variables so one change would also change all the references, but currently, I'm not sure which system that would be.

[adammontville]

Good comments @apiperCIS, and I tend to agree with that approach. Then:

• Standardized inputs will be denoted with GIx, where x is a positive integer incrementing from 1 across all sub-controls - we will call these global inputs
• Standardized measures will be denoted with GMx, where x is a positive integer incrementing from 1 across all sub-controls - we will call these local inputs
• Inputs specific to a sub-control will be denoted with Ix, where x is a positive integer within a given sub-control - we will call these local inputs
• Measures specific to a sub-control will be denoted with Mx, where x is a positive integer within a given sub-control - we will call these local measures
• Local inputs and local measures may not represent a set of contiguous positive integers, due to potential use of global inputs and global measures
• If we intend to list all required inputs or all required measures in a single table, the local inputs and local measures can be prefixed with their sub-control identifier
  • A sub-control identifier could simply be SCx.y or x.y, where x.y identifies the sub-control (i.e. SC3.1 or 3.1)
  • The complete identifier can be the concatenation of the sub-control identifier, a period (.) or dash (-), and the local input or local measure (i.e. SC3.1.M1 or 3.1-M1)

[wmunyan]

2nd bullet should call them "Global Measures", not "local inputs"

[adammontville]

Thanks, @wmunyan, you're correct. Fixed here:

• Standardized inputs will be denoted with GIx, where x is a positive integer incrementing from 1 across all sub-controls - we will call these global inputs
• Standardized measures will be denoted with GMx, where x is a positive integer incrementing from 1 across all sub-controls - we will call these global measures
• Inputs specific to a sub-control will be denoted with Ix, where x is a positive integer within a given sub-control - we will call these local inputs
• Measures specific to a sub-control will be denoted with Mx, where x is a positive integer within a given sub-control - we will call these local measures
• Local inputs and local measures may not represent a set of contiguous positive integers, due to potential use of global inputs and global measures
• If we intend to list all required inputs or all required measures in a single table, the local inputs and local measures can be prefixed with their sub-control identifier
  • A sub-control identifier could simply be SCx.y or x.y, where x.y identifies the sub-control (i.e. SC3.1 or 3.1)
  • The complete identifier can be the concatenation of the sub-control identifier, a period (.) or dash (-), and the local input or local measure (i.e. SC3.1.M1 or 3.1-M1)

[Tonyknz]

I would suggest dropping the dash within the concatenation specification and just leave the designator with the dot as a field separator.
If you are coding a system then it is easier just to look for a single character field separator within a function rather than having to look for multiple characters.

[adammontville]

@Tonyknz, good suggestion, thank you.