Monday, February 20, 2012

I have had a preliminary look at the following sources. I would be posting my comments about each of these in detail in the next few weeks.

Arthur, J.D., K.T. Stevens. 1989. Assessing the adequacy of documentation through document quality indicators. Software Maintenance, Proceedings., Conference on.

Carliner, Saul. 1997. Demonstrating Effectiveness and Value: A Process for Evaluating Technical Communication Products and Services. Technical Communication. 44(3): 252-65.

Dufty, David, Danielle McNamara, Max Louwerse, Ziqiang Cai, and Arthur Graesser. 2004. Automatic evaluation of aspects of document quality. In Proceedings of the 22nd annual international conference on Design of communication: The engineering of quality documentation (SIGDOC '04). ACM, New York, NY, USA, 14-16.

Hackos, JoAnn. 1994. Managing Your Documentation Projects. New York: John Wiley & Sons.

Hargis, Gretchen. 2000. Readability and computer documentation. ACM Journal of Computer Documentation. 24, 3: 122-131.

Hargis, G., Hernandez, A.; Hughes, P.; Ramaker, J.; Rouiller, S.;Wilde, E. 1998. Developing Quality Technical Information: A Handbook for Writers and Editors. Upper Saddle River, NJ: Prentice- Hall.

Huang, Shihong, and Tilley, Scott. 2003. Towards a documentation maturity model. In Proceedings of the 21st annual international conference on Documentation (SIGDOC '03). ACM, New York, NY, USA, 93-99.

Reilly, Annette. 1993. Professional recognition and respect through quality. Technical Communication. 40(2): 231-33.

Schriver, Karen. 1993. Quality in Document Design: Issues and Controversies. Technical Communication. 40(2): 239-57.

Sheffield, Michael. 1997. Quality Improvement: Benchmarking, Document Design, and the STC. Technical Communication. 44(3): 225-34.

Smart, Karl. 2002. Assessing Quality Documents. ACM Journal of Computer Documentation. 26(3): 130-140.

Smart, Karl, Kristie Seawright, Kristin Bell DeTienne. 1995. Defining Quality in Technical Communication: A Holistic Approach. Technical Communication. 42(3): 474-81.

Smith, Karl. 1996. What is Quality? InterCom. 42-43.

Spilka, Rachel. 2000. The Issue of Quality in Professional Documentation: How Can Academia Make More of a Difference. Technical Communication Quarterly. 9(2): 207-220.

Document Quality Indicators--article by Arthur and Stevens

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.
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:
  • 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. 
A preliminary investigation and extensive literature review [ARMY84, AFOT87, COLJ86, HORE86a, HORE86b, MURG86, SNEH851 reveals that the main, high-level Qualities of good documentation can be identified as: Accuracy,Completeness, Usability and Expandability.

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