JoAnn Hackos, PhD
CIDM Director

This is the third article in an eight-part series. The April 2005 article focused on the importance of estimating. The May 2005 article discussed the importance of planning. Now we look at the role of quality assurance in building customer-focused communication.

For most information developers, quality assurance represents a series of actions that ensure that content is accurate, complete, and meets customer requirements. These actions include

  • Reviews by subject-matter experts
  • Testing of content against product
  • Editing for consistency, compliance with standards, and focus on the customers’ needs

Each of these quality assurance actions is fraught with difficulties, especially when project schedules are seriously curtailed as companies push developers to release product more quickly. The pressure to meet the next deadline encourages organizations at all levels to forsake quality assurance, including even basic testing of products to ensure they perform as specified and contain minimal bugs.

Yet one very important mark of a mature organization is the ability to assure quality within a high-pressure environment. In fact, lean and agile approaches to product development place quality assurance at the top rather than the bottom of the list of critical project components. Just how can we apply lean methodologies to information development?

We believe that a topic-centered, domain-specific approach provides us with the environment we need to strengthen our quality assurance commitment and ensure that we deliver usable information to our customers.

Content reviews

Information developers recognize that reviews of content by subject-matter experts is essential to ensuring accuracy and completeness in the information they intend to deliver. Of course, we expect the information developers themselves to develop product expertise, especially after some years of working on the same kinds of information. At the same time, we know that others in the organization involved in the development of new products and features have an understanding of how products are expected to function that must be taken into account.

We also recognize that reviews by subject-matter experts in the organization are often difficult to obtain. Everyone on the product-development team is busy completing assignments. In most cases, team members have schedules for completing their work that do not include time for communicating with information developers or reviewing draft content. Even though everyone recognizes the importance of this collaboration, it is often on the bottom of the priority list.

Topic-based, domain-specific authoring provides two possible solutions to the fight for available time.

Topic-based authoring means that writers develop content in smaller, standalone modules that are later assembled into final deliverables. Because content plans are developed around lists of topics and writers are directed to begin preparing drafts in areas where content is more likely available, writers have an opportunity to collaborate with developers earlier in the product-development life cycle. Writers can ask developers to review task lists related to each individual’s area of expertise and then extend the task lists by linking conceptual and reference information to the essential tasks, making content reviews more productive than reviews of tables of content. Writers can ask developers to review snippets of essential content as task instructions are put together, facilitating feedback on the conceptual and reference information that will support the tasks. Concepts and reference are easier to envision when they are purposefully linked to tasks.

Product developers and other information resources like marketing, support, and training are more likely to review small topics or collections of topics more quickly when those topics are specifically directed to their domain specialties.

In organizations where writers develop domain-specific knowledge, the writers themselves become part of the team of subject-matter experts. In this capacity, writers are more likely to work closely with a small group of developers who are focusing on a particular part product feature. Since developers themselves are assigned by feature, this domain-focused arrangement provides a powerful commitment to quality.

Testing of documentation against the product

If reviews are difficult to schedule, product testing seems even more difficult. Many product testing teams have seen their staffs cut and schedules curtailed. At the same time, we clearly recognize that instructions must be tested if we are to ensure that they are accurate and produce the correct results.

In some information development teams, the writers are responsible for this most basic level of testing, as long as they can get access to product test systems. In other organizations, test systems are not available until late in the product-development life cycle or not at all, ensuring that the basic task instructions are likely to contain errors.

The solution, in these cases, must include the testing team in the process. Generally, testers are provided with documentation to follow as they perform the tests. Remember, however, that professional testers are not end-users. What may be clear and useful to them may be unusable.

That ’s why direct testing by members of the information-development team is essential. Information developers, especially interns or colleagues in other domain areas can act as surrogate users, depending upon the instruction rather than prior knowledge to perform a discrete task.

Information developers can, of course, test their own instructions against the products if they have timely access to test systems. However, testing your our instructions is never as effective as testing someone else ’s writing.

Editorial reviews

To reflect the assault on quality assurance even more, we have seen a continual degradation of editing functions in information development. Today, we know that there are fewer editors working in departments than there were 5 or 10 years ago. Some organizations retain editorial functions and others find that editors are the first to be eliminated.

Clearly, editorial review is even more important than ever in a topic-based authoring environment. Information developers are working on discrete topics that will be assembled into manuals, web sites, or help systems. The work of multiple authors is more likely to be intermixed in final deliverables in this case than when authors worked solely on their own books.

A topic-based, domain-specific collaborative authoring environment begs for the essential skills of a developmental editor. In most cases, such skills come in the form of a senior writer or project manager who has a long-term perspective on the product and information and has enough knowledge of the information architecture to look beyond individual topics to the whole approach to the customer.

The information architect is certainly part of this editorial review, with an overview of the topics to be created for the new release or new project. The architect/editor is able to ensure that the topics fit together and provide a sensible and usable information environment for the customer.

At the level of an individual or small group of topics, the same small groupings that are sent to product-development reviewers, a developmental editor is able to check for consistency of message, integration and flow of the information among topics, the presence of adequate conceptual, background, and reference support for tasks, and compliance with the architectural standards for structured development.

In too many organizations, I believe, editing is relegated to final copyediting, including proofreading; compliance with regulations in the form of copyrights, trademarks, and others; and final format checks. Although all of these tasks play a role in quality assurance, they seem easy enough to eliminate during reductions in force. Automated production systems can help reduce the time needed for final preparation of deliverables, but proofreading and regulatory compliance still need some human intervention. This is true despite the fact that senior management seems to believe that spelling and grammar checks are all powerful.

Only by elevating the role of quality assurance and making it an essential part of the process can we hope to avoid further inroads into editorial standards. It might even be wise to rename the job positions to avoid “editing ” as a title because that seems to raise red flags among managers who think of editors as their third-grade teachers.

Quality assurance provides us with the means to ensure that customers get what they need. Quality assurance means that we need to review, test, and edit our writing with a continuous eye toward customer requirements. Senior information developers who are skilled in user and task analysis and sensitive to the minimalist agenda and know much about the customers are the most valuable members of a truly collaborative team. They provide support and guidance to all the information developers strewn across the world and with diverse backgrounds, languages, and writing skills.