February 2008

From the Director

CIDMIconNewsletterJoAnn Hackos

Teamwork Is Essential

Traditionally, technical writers have worked alone even when they are part of a publications organization. Each writer is responsible for a document or set of documents, including designing and developing the content, and frequently, publishing the final information in various formats. Writers are often proud of their independence.

When we were issuing printed documents that stood alone, independence of design, writing, and publication was probably supportable. However, when we now work toward integrated and reusable content, a single-source strategy, and rigorously consistent content, independence has become severely strained. Independent actions must be replaced by a new team structure that encourages interdependencies and fosters constant communication.

Let’s look at the core requirements of a single-source strategy that relies upon structured authoring, minimalism, and a markup language such as XML DITA. From these requirements we can posit the team structure that we need to be successful.

  • First—all content must be planned as a whole
  • Second—all content must directly serve the needs of users for information and action
  • Third—all content must be consistently structured
  • Fourth—all content must follow the rules of an XML-based content structure

Each of these requirements must be fulfilled if we are to build a repository of relevant and useful content that can be mixed and matched to create a plethora of user-oriented deliverables. Underpinning these requirements is teamwork—requiring the close communication and intermingled actions of a professional information-development staff.

All content must be planned as a whole

Because we can no longer define our content in terms of the chapters and sections of individual deliverables or help files, we need to take a broader view of the planning process. The process used in many publications organizations for planning is very high level. It usually begins with business requirements including due dates, delivery outputs, and translation. Unfortunately, it usually ends with the same business requirements. Many documentation plans I’ve reviewed contain little more information about the project. The deliverables defined in the plans are farmed out to individual team members.

In my 1994 text, Managing your Documentation Projects, I promoted an estimating method that was itself derived from a book-oriented deliverable plan. Each book and help system became part of the total project estimate, based on an average hours per page, adjusted for project complexity. The planning, however, extended beyond the page into a content plan for each deliverable, detailing the content to be produced, usually below the chapter level. Many organizations use these methods

In my 2006 text, Information Development: Managing your Projects, Portfolio, and People, I moved to a topic planning process to accompany a topic-based estimating scheme. Not only can we estimate projects based on individual topics, but we can also plan the content at the topic level. The innovation of the annotated topic list allows us to designate how the content is organized at the topic level and how it is distributed through the various deliverables. The publications team develops the annotated topic list as a team, with input from writers, information architects, and others who understand the requirements of the users and the product. Using the annotated topic list, publications teams should know what topics need to be written, who will write them, and where they will be used.

All content must directly serve the needs of users for action and information

Research in minimalism demonstrates that most people coming to technical information do so to achieve a specific end, typically in service of completing a task. They seek information that supports actions and helps them reach a work-oriented goal. As a consequence, we need to design and develop information that closely adheres to the users’ minimalist agenda.

During the development of a team-oriented information project, writers and architects must work together to ensure that the topics they plan to create have a clearly defined purpose. Does a procedure further a particular need by the users to achieve a goal? Or, does a procedure simply explain how to use an interface for its own sake? Without an obvious link between a procedure and the users’ task-oriented needs, the procedure topics have little function.

So—do we as a team need to define why we provide reference data and to what end do we write about concepts or provide technical background? If the topics we define as concept or reference topics in our annotated topic list are not clearly linked to the performance of a task, it is unlikely that users will find the information valuable.

The minimalist agenda tells our team that we should only write what the users need to be successful in working with our products. All other content is superfluous.

However, we also notice that many technical documents contain information that is not clearly defined nor appears to fulfill any well-defined user requirement. We find low-value topics repeated in more than one deliverable, and we find topics that might have high value missing from the content suite.

To ensure that content is relevant, our team members need to perform task analyses, understanding the users’ agenda and supporting high-value user scenarios for performing tasks and reaching goals. Without this knowledge as a team, we are likely to write topics that are rarely if ever read at all.

All content must be consistently structured

Structured authoring requires strict discipline, following the patterns established by a custom Information Model. Writers accustomed to working independently on their own deliverables now must follow a pattern for content that has been designed by the team architects. Unlike the patterns we have long developed in a desktop publishing environment, a structured architecture defines the specific units of content that are to be included in tasks, reference topics, and conceptual information. Where we once wrote paragraphs and developed bulleted lists, our structured Information Model requires that we write pre-requisites, definitions, examples, results, post-requisites, and more.

Teams may begin with the basic requirements defined by DITA. But the DITA content units are only the beginning and certainly not specific enough for the demands of structured authoring. The generic content units must be explicitly defined for the product and users that each team supports.

For example, a pre-requisite in one project might include required tools and safety precautions, while another project might demand a set of software configurations.

In addition to a consistent structural pattern defined in the Information Model, the team must ensure that every team member understands the patterns. Such understanding comes only from team-level reviews of each other’s content and reviews by the information architect or editor. Some writers grasp the concept of structured authoring quickly; others require guidance, especially when dealing with the often-convoluted structures of legacy content.

All content must follow the rules of an XML-based content structure

Moving content to XML from desktop publishing systems requires a new discipline among our team members. To maintain consistency in the content itself and to ensure that output renders properly, everyone must use the same code structure in XML. For example, we may design our coding to require that an <image> be included as part of a <fig> tag. The proper coding requirement might be <fig><title>This is a figure.</title><image href=X></image></fig>. However, if a team member codes the <image> outside of the <fig> tag, the rendering is likely to be different. Even small differences like this one can result in significant differences in rendering.

The team process required can be called “code review.” First, of course, the team must set specific requirements for coding various kinds of structures that must be consistently maintained in the documents. Then, team members must review one another’s code to ensure that the structure is correct. A code review during development will reduce the time needed during production to fix errors.

Teamwork Remains Essential

I find that it is no longer possible in a managed content environment to have the staff work independently. So much must be thought through and organized carefully that everyone must be involved and must understand and appreciate the need for close collaboration. Virtual or co-located—it makes no difference. We need real teams that play by the same rules.

The team members need management as well. Part of that management will involve the standard project management work—scheduling, resourcing, supporting. Another part of management will involve information architecture—designing and problem solving. Still another part will be the people management of keeping the team working smoothly. Hands-off management no longer applies.

Coordination, communication, collaboration, teamwork—these are all operative words for today’s and future technical communication professionals.CIDMIconNewsletter