Topic-based authoring has been a mainstay of technical information development since we first began developing help systems. We learned quickly enough that we couldn't split our existing books into help topics by making every heading level a new help page. Information originally designed with a narrative flow no longer made sense nor assisted users in finding exactly the content they needed. We had to rethink the type of information that our help systems should include and create a new set of standards for its development. The result is topic-based authoring.

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.

If one of your business goals is to use information topics in multiple deliverables, you need to build a repository of topics that are clearly defined according to your standard set of information types. Your repository is also characterized by the metadata attributes you associate with you topics.

DITA provides you with such a standard as a starting point. DITA gives you the capability to expand upon its core information types when you need to accommodate the special needs of your customers and your information.

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.

In most cases, you will find lots of tasks, containing step-by-step instructions for reaching a specific goal. The dominance of the task in technical information is why DITA includes the task as one of the three core information types.

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 user wants to know the steps of a task, they can skip background information 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.

Consider an example in the semiconductor industry. A great deal of detailed information about a chip design is contained in an information type called a register description. Although a register description falls into the class of reference information types, it has some very specific and detailed content. By specializing on the standard reference information type, you can build a register description specialization that standardizes the content with appropriate XML elements names, assisting the writers and providing additional metadata to facilitate searches. Many similar opportunities for specialization may present themselves in your content. But be careful to exhaust the possibilities of the standard information types before pursuing the differences.

The more differences you present to writers and readers, the more opportunities there are for confusion. With too many choices of information types, an information developer is more likely to chose incorrectly. With too many subtle differences in the presentation of information, your users are more likely to become confused when they are unable to find the standard set of content that they have come to expect.

Introduction to DITA: A Basic User Guide to the Darwin Information Typing Architecture, by Comtech Services, Inc.

See Portuguese translation of this page.