JoAnn Hackos, PhD
This is the second article in an eight-part series. The first article appeared in the April 2005 issue ofInformation Management News and focused on the importance of estimating.
“We really don’t plan. It takes too much time, and the product keeps changing.”
Despite arguments to the contrary, we learn from CIDM managers who develop detailed information and content plans that the efforts pays for itself. Content planning, when done in the context of user requirements, decreases information-development time and alters the distribution of activities during the information-development life cycle.
Too often, information developers feel compelled to wait until products are stable before beginning to outline the topics they need to develop for users. In groups that focus on documenting the user interface rather than on documenting user tasks and concepts, planning tends to be neglected because so much of the plan depends upon the product. In contrast, groups that focus on user tasks and concepts can begin planning long before product interface details are established. Far fewer changes occur with respect to user goals for a product release than with interface details.
Rather then spending time rewriting detailed instructional topics in the midst of rapidly occurring product changes, during the information planning phase of a project, information developers should focus their attention on the users’ goals. They can define use cases and scenarios that describe how users will interact with the product. They can focus on what users need to know to be successful and what they must learn how to do.
By concentrating your planning time on the users’ need for information to support their successful use of your product, you can postpone including the user interface details until the engineering changes settle down. Once product details are better defined, at least in terms of the user interface and the ways in which users will need to perform tasks, these details can be added quickly and easily to your predefined set of topics.
Early input from product marketing, participation in product definition discussions, and input from the user community all provide sufficient resources to enable thorough, efficient, and productive planning early in the project life cycle. We find that user goals rarely change with engineering changes, although the details of task performance may be altered.
Topic-based architectures facilitate early planning
Too many organizations, in my view, restrict their information planning to lists of final deliverables.
“We need one user guide, two command reference manuals, an administrative guide, and a help system.”
Sounds like ordering from one of those ‘50s Chinese restaurant menus: we want one from column A and two from column B. Usually the list of deliverables for the current release is the same as the list for the previous release anyway. We really don’t know much about the scope of work required to complete the deliverables and meet the deadlines.
When your organization decides to pursue a topic-based architecture, you need to make a firm commitment to detailed planning. In fact, the level of planning required may come as a surprise because planning of this sort has been relegated to individual writers rather than as a core activity of information architecture. In most book-centric information models, the details of a book’s content is left to the individual contributor. Of course, that results in duplication of topic content among deliverables, even though the content may be written differently. It also results in missing content that no one has thought to include in their books. Because topics are not planned across deliverables, fewer or no opportunities for reuse occur. Even if reuse were possible, the idiosyncratic nature of the content development precludes it.
In topic-based authoring, reuse is an important business and architectural assumption. Topics must be planned from the beginning so that their reuse potential is optimized. Without detailed topic-based planning, individual topics may continue to resist use in more than one context.
Topic-based planning is critical
Topic planning must become a critical part of the information-development process in a well-managed organization, even if you are still producing traditional book-based deliverables. We suggest creating three lists to plan topics: conceptual and background information, user tasks, and detailed reference information.
Conceptual and background information provides the definitions and explanations that users need to perform tasks successfully. For example, in developing our tool for project estimating, we included discussions on the importance of estimating and the way estimating could be used to establish project schedules and staffing. Although people familiar with estimating could certainly skip over this background information, those new to project estimating were best served by understanding why it is important.
Task information supports the user goals in getting work done. In our project estimating tools, we included instructions on using the dependency calculator, setting up estimating spreadsheets, and determining how many topics were new, changed, or unchanged. Each of these tasks was supported by a detailed instruction.
Reference information, although often included with tasks, can also be profitably planned as separate topics. In our example of an estimating tool, reference information might include lists of typical hours per topic developed by experienced project managers. By keeping reference information separate, we can more easily ensure that it is updated in a timely manner.
You may want to create a table of topics as follows:
|Conceptual information||Task information||Reference information|
|The value of estimating to your organizationProject estimating adds accuracy to your detailed project schedule and resource requirementsDependency calculations add a layer of project reality to your topic estimates||Creating an estimating spreadsheetUsing the dependency calculator||Typical topic-based estimates among industry leaders|
Once you have all the topics delineated, you can add information about the time and cost to create or modify each topic and estimate your schedules and deadlines for the project as a whole.
The detailed planning at the topic level can be extended to your planning for book-based deliverables or Web and Help system deliverables. The planning table above can easily lead to a linear table of contents and a set of links for online delivery.
Reuse also becomes obvious with detailed topic-based planning. Topics can be designated for use in more than one context. A conceptual guideline for project planners may include only the conceptual and reference information, while a user guide may focus on tasks and background knowledge required to complete the tasks successfully.
Certainly, information and content plans must contain more information than information architecture details. Most project managers include information about schedules, resources, dependencies, and risk factors. For a complete description of information and content plans, see my text, Managing your Documentation Projects (Wiley 1994). All the required content is carefully outlined in that resource.
Remember that planning may seem an impediment to making a tight schedule. In fact, planning is essential to any schedule, tight or loose. As a best practice in information management, be certain to include careful planning in an early phase of your project.