Revision of Topic-Based Authoring from Tue, 2006-03-14 15:50
Authoring in topics provides information developers with a way to create distinct modules of information that can stand alone for users. Each topic answers one question: "How do I ...?" "What is ...?" "What went wrong?" Each topic has a title to name its purpose and contains enough content for someone to begin and complete a task, grasp a basic concept, or look up critical reference information. Each topic has a carefully defined set of the basic content units that are required and accommodates other optional content. As information developers learn to author in topics and follow sound authoring guidelines consistently, we gain the ability to offer information written by many different experts that looks and feels the same to the users. Not only has topic-based authoring become the norm for well-designed help systems, information architects have learned that formulating consistently structured topics facilitates readability and information access in traditional, more linear book structures. Readers are able to identify task-based topics within sections and chapters because the tasks look the same and contain the same essential content units. Readers learn that conceptual and background information is always located in the same position in the table of contents with respect to the tasks. Readers come to depend upon standard reference sections that contain similarly structured details for ease of lookup. The core information types in DITA support the structures that underlie most well-designed technical information. Any organization that follows best practices in formation architecture will find the core DITA structure a good fit. But they also challenge us to become even more disciplined in structuring information according to a set of carefully defined business rules. The benefit of such disciplined information structuring is the consistent presentation of information that helps you build reader confidence and simplify the reader's task of knowing how to navigate and use your information.
Benefits of topic-based authoring
Authoring in structured topics provides you with a sophisticated and powerful way to deliver information to your user community. You will find benefits that decrease your development costs and time to market, as well as provide increased value to your customers:
- Structured topics contain only the information needed to understand one concept, perform one procedure, or look up one set of reference information.
Structured, topic-based authoring promotes consistency in the presentation of similar information. - Topics can be reviewed by subject-matter experts as soon as they are ready. They need be reviewed only once, even if they appear in multiple deliverables, reducing the burden on reviewers.
- Topics can be translated before entire volumes are complete, reducing the time to market for global customers. Topics in multiple languages can
be combined into language-specific deliverables without extra desktop publishing time and expense. - Assembling topics into multiple deliverables can be automated, reducing production time and costs.
- Consistently structured topics are easier to reuse in multiple deliverables.
- Structured topics may be combined in new ways to meet changes in product solutions, work structures, geographies, industries, or other customer configurations.
- Topics are easier to update immediately instead of waiting for the next release of an entire library of documents.
- Consistently structured topics help users build a firm mental model of the types of information you are presenting.
- Consistently structured topics help users navigate more quickly to the information they need.
Defining information types for your topics
If your information is like most in the technical information industry, you have a great diversity of structures in your information, especially if those topics are embedded in the threaded, narrative sections and chapters of books. Your first job is to inventory your content to identify its range and diversity.
Accompanying tasks, you are likely to find background, description, and conceptual information that explains what something is. DITA labels such supporting information "concepts". You will also find tables, lists, diagrams, process flows, and other information that can be labeled as "reference," the information that no one wants to memorize but must be easy to look up. Once you have completed your content inventory, you need to carefully analyze the three core information types provided with DITA. The standard structure for task,
concept, and reference is presented in the DITA specification. Experiment with accommodating your content to the standard structure.
In most cases, your content easily fits into a standard DITA structure. Where you may encounter difficulties is with the diversity of your own content rather than with the DITA information types. Some of the content in your inventory will not even meet your own guidelines. Often, that content was written by people long gone from your organization or was influenced by subject-matter experts who wanted it their way rather than following your authoring guidelines. Our recommendation is to focus on the essential underlying structure of your content rather than the idiosyncrasies and accidents of individual writers over the years. If you find an odd structure in a task, for example, ask if that structure is the best way of conveying the information to the user or if the task can be rewritten following the structure of a standard DITA information type. Most of the time, you will find that the standard is the best solution. One of the more common problems you will find with some of the content you examine is mixed structure. Tasks start out with long discussions of background information. Concepts end up including step-by-step procedures. Tables of reference material end up with concepts in the footnotes or tasks incorporated into table cells.
Although mixed information types are possible in DITA, we don't recommend using them. Consider that by separating information carefully and rigorously into the neat, consistent information-type buckets provided, you will have information that you can present much more dynamically and flexibly to users. If a users wants to know the steps of a task, they won't have to skip over background that they don't want to think about yet. You can refer them to that conceptual and background information through a related-topic reference or a hypertext link rather than embed lengthy conceptual information in the task. By chunking your information according to well-defined information types rather than combining types randomly, you gain flexibility in distributing your information to people who need it most. You also make the relationships between chunks of information more obvious. If you believe that users will profit from reading background information before performing a task, by using related-topic links, you can ensure that they know about the relationship and why reviewing the concept or background is advantageous.
Adding new information types
Although we find that most technical information fits neatly into the standard DITA information types, we recognize that you may discover that you have special information types that cannot be accommodated by the standard content units or that you want to label those content units with more descriptive XML tag names. At that point, you need to pursue specialization.
Introduction to DITA: A Basic User Guide to the Darwin Information Typing Architecture, by Comtech Services, Inc.
- Printer-friendly version
- Login to post comments
- 78619 reads