Article: Assessing the Adequacy of Documentation Through Document Quality Indicators
Arthur, J.D., K.T. Stevens. 1989. Assessing the adequacy of documentation through document quality indicators. Software Maintenance, Proceedings., Conference on
Case study results of a research effort funded by the Naval Surface Warfare Systems (NSWC) at Dahlgren, Virginia.
Arthur, J.D., K.T. Stevens. 1989. Assessing the adequacy of documentation through document quality indicators. Software Maintenance, Proceedings., Conference on
Case study results of a research effort funded by the Naval Surface Warfare Systems (NSWC) at Dahlgren, Virginia.
Can we tie doc quality to content not making it to the doc on time? Missing content? Can we measure adequacy of docs? Can that be a quality indicator?
Inadequate doc quality causes issues. Subsequently, many system changes never appear in life-cycle documents crucial to the support of maintenance activities. As expected, such deficiencies exact a significant price during the maintenance process, and contribute to the familiar claim that more than one-half the total life cycle costs are incurred during the maintenance phase [BOEB76, LIEB781.
Article suggests one approach to evaluating the adequacy of documentation relative to the system that it purportedly describes.
Article asks 2 questions: What constitutes "adequate" documentation?How does one "measure" the adequacy documentation?
Investigations of these questions leads to 2 key findings:
Qualities are the very abstract characteristics of Adequate Documentation, defined as the essential components of adequate documentation
Relative to documentation quality, Accuracy can be defined as: the consistency among the code and all documentation of the code, for all requirements.
For the purposes of computer documentation, a set of documentation is complete if all of the required information is present. Hence, incorporating standards into the description, a more precise definition for Completeness in the context of document quality is: the existence of all documents required by a set of standards.
Relative to assessing documentation quality, Usability is more appropriately defined as the suitability of the documentation relative to the ease with which one can extract needed information.
In concert with the notion of document maintainability, a more precise definition for Expandability is: the capability of the documentation to be modified in reaction to changes in the system. This Quality is assessed through measures reflecting ease of modification.
The first step in assessing the adequacy of documentation entails the identification of desirable Qualities that one wants to measure.
A subsequent search for measurable surrogates has led to the synthesis of Document Quality Indicators (DQIs). A DQI is defined to be a triple whose elements are: a Quality (of a document), a Factor (refining a quality), and a Quantifier (measuring a Factor)
One measurement of this DQI (and hence, one measure of accuracy) might be based on metrics that employ data derived from a simple checklist or matrix-oriented template.
Nonetheless, as conveyed by the examples given above, Factors of Quality are still missing the "concreteness" necessary to support measurement. Quantifiers, on the other hand, are measurable characteristics, and through their direct link to Factors, provide for Factor assessment.
Clearly, the examination and evaluation of project documentation is difficult - many issues still remain unresolved.
Four future research directions that require investigation before a total process for document analysis can truly be realized.
The Quest for Additional Quantifiers
Metric Identification and Formulation
Metric Identification and Formulation
A Validation of the Assessment Procedure
Inadequate doc quality causes issues. Subsequently, many system changes never appear in life-cycle documents crucial to the support of maintenance activities. As expected, such deficiencies exact a significant price during the maintenance process, and contribute to the familiar claim that more than one-half the total life cycle costs are incurred during the maintenance phase [BOEB76, LIEB781.
Article suggests one approach to evaluating the adequacy of documentation relative to the system that it purportedly describes.
Article asks 2 questions: What constitutes "adequate" documentation?How does one "measure" the adequacy documentation?
Investigations of these questions leads to 2 key findings:
- The formulation of a general theory of documentation analysis based on the Document Quality Indicator @QI) concept,
- The development of an Evaluation Taxonomy that relates document Qualities to Factors and document Factors to Quantifiers.
Qualities are the very abstract characteristics of Adequate Documentation, defined as the essential components of adequate documentation
Relative to documentation quality, Accuracy can be defined as: the consistency among the code and all documentation of the code, for all requirements.
For the purposes of computer documentation, a set of documentation is complete if all of the required information is present. Hence, incorporating standards into the description, a more precise definition for Completeness in the context of document quality is: the existence of all documents required by a set of standards.
Relative to assessing documentation quality, Usability is more appropriately defined as the suitability of the documentation relative to the ease with which one can extract needed information.
In concert with the notion of document maintainability, a more precise definition for Expandability is: the capability of the documentation to be modified in reaction to changes in the system. This Quality is assessed through measures reflecting ease of modification.
The first step in assessing the adequacy of documentation entails the identification of desirable Qualities that one wants to measure.
A subsequent search for measurable surrogates has led to the synthesis of Document Quality Indicators (DQIs). A DQI is defined to be a triple whose elements are: a Quality (of a document), a Factor (refining a quality), and a Quantifier (measuring a Factor)
One measurement of this DQI (and hence, one measure of accuracy) might be based on metrics that employ data derived from a simple checklist or matrix-oriented template.
Nonetheless, as conveyed by the examples given above, Factors of Quality are still missing the "concreteness" necessary to support measurement. Quantifiers, on the other hand, are measurable characteristics, and through their direct link to Factors, provide for Factor assessment.
Clearly, the examination and evaluation of project documentation is difficult - many issues still remain unresolved.
Four future research directions that require investigation before a total process for document analysis can truly be realized.
The Quest for Additional Quantifiers
Metric Identification and Formulation
Metric Identification and Formulation
A Validation of the Assessment Procedure
Samir:
ReplyDeleteI like that this article talks about the difference between "quality" and "usability". Clarifying that, "high-level Qualities of good documentation can be identified as: Accuracy,Completeness, Usability and Expandability."
Is it your intention to create a DQI such as a simple checklist or matrix-oriented template?