Calculating Documentation Cruft

It's easy to describe documentation cruft, and often easy to identify it once you see it, but it's hard to estimate how 'crufty' a document actually is. Furthermore, it's often hard to convince the creators of a document that 'their baby' isn't as beatiful as they believe it to be.

Ambler, Scott W. Dr. Dobb's (2007). Articles>Documentation>Assessment>Minimalism

Comparative User-Focused Evaluation of User Guides: A Case Study    

A comparative evaluation of two user guides,--the document traditionally used by a company and a model document designed on the basis of research results and recommendations,--was carried out using a number of complementary approaches focusing on the user. The quality and suitability of these documents for the target audience were assessed in terms of content, structure, presence of certain organizational devices (such as headings) and pictures included. The results revealed that the model document was more attractive, more efficient, and better adapted to users' needs, thanks to its modular organization (being structured according to "functions"), a large number of pictures, the presence of headings, and rationalization of the vocabulary used.

Ganier, Franck. Journal of Technical Writing and Communication (2007). Articles>Documentation>Assessment>User Centered Design

A Comparison of Two Evaluation Techniques for Technical Documentation

This study compared two evaluation techniques, Usability Testing and Cognitive Walkthrough, in their ability to identify errors in aviation maintenance documentation. The techniques were evaluated to see how much unique information they each produced as well as the type of errors identified. Results showed that the techniques were complementary in their findings and both are recommended in the development of technical documentation.

Rogers, Bonnie Lida, Chris Hamblin and Alex Chaparro. Usability News (2005). Articles>Documentation>Assessment>Usability

Documentation and Training Productivity Benchmarks    

Investigates how computer-industry companies create end-user documentation and training materials, and how they measure productivity. Describes results of interviews of eleven managers of publications or training departments.

Barr, John P. 'Jack' and Stephanie Rosenbaum. Technical Communication Online (2003). Articles>Documentation>Assessment

Documentation Metrics: What Do You Really Want to Measure?  

Examines several metrics--systems for measuring production and production standards--to determine their value to technical communicators. He argues that qualitative metrics are more meaningful than quantitative ones.

Le Vie, Donald S., Jr. Intercom (2000). Articles>Documentation>Assessment>Heuristic Evaluation

Documentation Quality Metrics

To implement any continuous improvement process, you have to measure your progress. This is where metrics come in. Have you been struggling to create a process for measuring your technical documentation? If so, this article provides the information you need to get started.

Cohen, Jules. Carolina Communique (2004). Articles>Documentation>Assessment

Evaluating and Choosing a Service Provider  

Small- to middle-sized companies are often dependent on third-party service providers to complete tasks related to documentation production. Formally evaluating service providers is one way for documentation managers to ensure that their company and documentation team are getting maximum service, top quality, and competitive prices. Evaluations must be carefully planned and implemented in order to produce reliable results. The planning phase lets the documentation managers “set the stage” for an evaluation by defining and communicating the main objectives. The subsequent implementation phase lets participants gather the key information required to select the best service provider.

Weirich, Margaret. STC Proceedings (2003). Articles>Documentation>Outsourcing>Assessment

Evaluation Toolbox for Aviation Technical Publications

This article describes the Evaluation Toolbox (Chaparro et al., 2004) - an aid to understand the process of evaluating the usability of aviation maintenance documentation -- from the initial development stage through the final pre-publication stage. This toolbox provides techniques to help technical writers better understand their users and to evaluate their documentation more effectively and efficiently.

Rogers, Bonnie Lida, Chris Hamblin and Alex Chaparro. Usability News (2005). Articles>Documentation>Assessment>Usability

Key Issues in Conducting and Writing Integrated Assessments  

Integrated assessments of environmental concerns consider the economic and social effects of a change as well as the environmental effects. Topics that should be addressed in such an assessment and the weight given 10 each are thorny problems for the assesment team and writer to deal with. The results of a workshop of experts in public policy, utility management, regulation, political science, government, technical communication and environmental science identified and characterized the key issues in shping and defining this new genre of environmental writing.

O'Hara, Frederick M., Jr. STC Proceedings (1995). Articles>Documentation>Environmental>Assessment

Maintaining Quality Control in Documentation  

If all of us were more focused towards quality in our lives, we would have it in abundance. We would have higher satisfaction levels and therefore, have lesser complaints. This paper presents cases and reasons why user manuals and guides are not up to the expected standards. Do we need to go beyond checklists before shipping a document? Are reviews and checklists sufficient? This paper briefly talks about the measures that we could take to ensure that a good document is delivered.

Singh, Neelam. STC Proceedings (2002). Articles>Documentation>Assessment

Manual Evaluation Workshop  

Experts in document design will analyze your document for organization, page layout, writing style, and use of graphics. Each document analysis lasts approximately 30 minutes. You must have a ticket for this session and bring a document to be evaluated.

Brogan, Barbara B. STC Proceedings (1995). Articles>Documentation>Assessment

Method to Evaluate Manuals and Online Help  

In these testing times when time to market for software is constantly diminishing, the demand to make manuals and online help targeted, faster, cheaper and better is a tall order. While methods and tools are being constantly developed to help us do our work faster, and better, measuring the quality of the written word remains a deficient arena. Technical Communications gurus advocate methods like surveys and usability to make better end products. However, this requires good infrastructure and management support to carry out. This paper provides a method to evaluate technical manuals and online help for software products. It discusses how you can gauge a manual’s quality and suggests a method to quantify its effectiveness. It is cheap to implement and is customizable for your organization. All you need is good knowledge of your audience, and some faith and persistence!

Santhanam, Raji. STC Proceedings (1999). Articles>Documentation>Assessment>Help

Methods for Documentation Testing in Technical Publications Quality Assurance  

Traditionally, verification of documentation procedure accuracy follows a standard model: technical communicators prepare a draft, which is submitted to subject matter experts for review. This process hinges on a number of factors that can adversely affect the quality of the review. Higher quality reviews are conducted by staff tasked specifically to test and review the draft procedures, and supply specific feedback by means of an established procedure. A well-established method of documentation testing provides several benefits to an organization. These include customer satisfaction, reduced costs, improved overall product quality, and improved document draft correction.

Lippincott, Richard J. STC Proceedings (2003). Articles>Documentation>Quality>Assessment

Obtaining User Feedback: How Useful Are Your Online Help Systems?  

Surveys or questions posed to users may not be entirely useful when determining whether a user's experience with the help feature was successful or not. The author provides instructions on implementing a tool that will provide this kind of feedback.

Webb, Jeremy. Intercom (2006). Articles>Documentation>Online>Assessment

Performing Publications Needs Assessments  

A publications needs assessment is a way to identify and analyze documentation and publishing needs for a project, group or company. The technical communicator can use these assessments to ensure that the proper documentation and publishing services are provided. This paper describes a four step approach to performing publications needs assessments.

Devlin, John T. STC Proceedings (1993). Articles>Documentation>Planning>Assessment

Quality Measurement for Documentation: Different Tools for Different Needs  

The world of technical communication continues to search for a reliable information metric that is easy to apply and widely accepted. Although that goal eludes us for the moment, we can make a choice among competing metrics based on an understanding of their strengths and weaknesses, and appropriateness for different audiences. Two kinds of metrics, ordinal scale metrics and surface feature metrics, seem to meet many of our needs. The differences between them lie in their choice of measurements and the methods of applying the measurements.

Hunter, Claudia M. STC Proceedings (1993). Articles>Documentation>Quality>Assessment

Readable Computer Documentation    

A retrospective look shows earlier advice still relevant to both predicting and producing readable writing. For prediction, refined readability formulas with stronger criterion passages and updated familiar -word lists have appeared, although the computerization of readability tests sometimes encourages misapplying or misinterpreting them when screening text. For production, attention to sentence construction, word characteristics, and information density remains relevant to both drafting and revising computer documentation for readability, especially since reading speed and reader preference often interact with comprehension in practical settings.

Klare, George R. Journal of Computer Documentation (2000). Articles>Documentation>Assessment>Usability

Resources

Requesting a quote for outsourced documentation services can be confusing and frustrating. Often it means that managers in IT, engineering or HR must negotiate with professionals whose skills they cannot effectively assess. This can easily lead to inappropriate expectations and disappointment.

Dawson, Colin. Info Action (2000). Articles>Documentation>Outsourcing>Assessment

A Standardized Analysis Method for Customer Inquiries  

The Documentation Development Department (DDD) of Hitachi has been improving its software manuals by analyzing inquiries from its customers to the Hitachi Computers Customer Answer (HCA) center. In order to improve inquiry application procedure the DDD isolated and studied inquiries about Hitachi’s workstation, OA software products, from October, 1991 until March 1992.

Ieda, Fumitaka. STC Proceedings (1993). Articles>Documentation>Assessment>Surveys

What is Good Documentation?

This article lists some basic metrics for determining whether documentation is useful or not. Users' needs and issues of accessibility are highlighted.

TechScribe (2003). Articles>Documentation>Assessment