Topic-Based Writing in DITA
- Books, Topics, and Webs of Information
- Advantages of Writing in Topics for Writing Teams
- DITA Topic Types
- Task Orientation
- Minimalist Writing
- To Wrap Up
- Topic-Based Writing Checklist
- Task Analysis Form
This chapter is from the book
This chapter is from the book
This chapter is from the book
What's a topic other than a conversational piece? In technical information, a topic, which is sometimes called an article, has a title and some content. A topic has just enough content to make sense by itself but not so much content that it covers more than one procedure, one concept, or one type of reference information.
Although a topic should be self-contained, it shouldn't live alone. For information delivered with most technical products, services, or technologies, a topic needs a home in a larger, organized collection of topics. That collection can then be packaged and delivered in an output format such as HTML web pages, online help, or a PDF manual.
Darwin Information Typing Architecture (DITA) is specifically designed to support topic-based writing. With its modular-based architecture, semantic XML elements, and powerful linking features, DITA can help you create and maintain topic-based, or componentized, technical information.
Writing topic-based information has advantages for both the users of your products and for your writing teams. However, separating your information into different topic types isn't enough. To ensure that your information meets the needs of your users, you need to understand how to write minimalist, task-oriented information.
Books, Topics, and Webs of Information
Books are great for some things, such as mystery novels, complex scientific concepts, and philosophical ponderings. However, books aren't the best vehicle for delivering targeted technical content to users who have real-world tasks to complete.
Information organized in a narrative book model typically has these characteristics:
- Beginnings, middles, and endings intended to be read linearly from beginning to end
- Chapters or sections that often mix task, conceptual, and reference information
Although the narrative book model works well for novels and some nonfiction books, it's not well suited for technical information that's delivered with a product. When it's time to adjust the valves on the motorcycle, users don't want to read a novel. They want to open the motorcycle manual, find that one specific task, and move on.
A topic is a self-contained unit of information. An effective topic covers only one subject. Each topic is long enough to make sense on its own, but short enough to stick to one point without expanding into other subjects.
A topic typically answers one of these questions:
- How do I do it?
- What is it?
- What is the process?
- How do I fix it?
Because most users need only a small amount of information at a time, you should create information that can answer specific questions discretely without requiring extensive reading across large amounts of interconnected content.
Separating information into discrete topics helps you to:
- Design new information more easily and consistently
- Eliminate unimportant or redundant information
- Identify common or reusable topics or pieces of content in topics
All topics, regardless of their purpose, have the following characteristics:
- Meaningful titles
- Ability to stand alone from other content
- Logical organization
- Links to other topics that contain related information
You organize and link topics to create a coherent web of information, as shown in Figure 1.1. Eventually, the output of this collection of topics might be an online help system, a PDF manual, or a website. Although a web of topics might seem chaotic at first, DITA can help you organize and link topics so that users don't get lost.
)
Figure 1.1 Linked and organized topics that form a web of information.
By writing your information in discrete topics, organizing those topics into logical collections, and then linking related topics to each other, you can create a web of information that is easy to navigate, easy to understand, and easy to consume.