Skriftlig Info ➜ DITA publishing ➜ DITA topics ➜ About DITA topics
Here is the "official" description from Oasis:
A topic is a unit of information with a title and content, short enough to be specific to a single subject or answer a single question, but long enough to make sense on its own and be authored as a unit.
Oasis, "DITA topics", docs.oasis-open.org, [REF]
Wikipedia has a page on topic-based writing. This description of a topic is provided:
A topic is a discrete piece of content that:
- focuses on one subject
- has an identifiable purpose
- does not require external context to understand
Topics can be written to be independent of one another and reused wherever needed.
Wikipedia, "Topic-based authoring", en.wikipedia.org, [REF]
Based on these explanations, I define a DITA topic as follows:
A DITA topic is a stand-alone data module that contains multimodal text. The module has a title and enough information to explain a specific procedure or concept. Each topic is written in such a way that it is independent of other topics and can be reused in different publications whenever appropriate. The content of the topic is presented in a flat structure. Structure and context are established when the topic is inserted into a topic map together with other topics.
Each topic (topic) contains a number of elements. Each element has a start tag and a stop tag. The elements are inserted in a structure and sequence that follows the basic rules of DITA. The multimodal text the elements contain forms the overall message the topic conveys.
There are some basic properties that each topic must satisfy:
Focus
It must be focused and must describe only one subject.
Purpose
It must have a purpose. This purpose is, for example, an explanation, a procedure, a specification or a detailed description.
Reusable
Provided that the information in the topic is correct, you must be able to take it out of a given publication and use it again in another.
Generic
It must not assume a specific location in a defined publication or context. You must be able to place a topic anywhere in any publication.
Independent
It must not assume that the reader has read other information first or has otherwise been explained something first. It must be completely self-contained.
No references
It must not contain text with references to other topics. It must not refer directly to anything explained elsewhere in the publication.
Format Independent
It must not assume that it will only be published in a specific format, for example, only PDF.
In this context, it is important to understand what is meant by "self-contained". The idea is that the reader shall open the book, find exactly what he or she needs in an self-contained section, and then close the book again. It shall not be necessary to have read anything else in the book first to get the full benefit of the text.
Let me illustrate it with an example.
When I got into the car, I accidentally bumped into the steering wheel, and the steering wheel lock was activated. No danger, I thought, and pressed the start button. Whereupon the car happily announced that it would not start when the steering lock was engaged. What do you do? The owner's manual was in the glove compartment, and I looked up "steering wheel lock" in the index register. On page 152 I found a simple five-step procedure that explained what I had to do. Everything was on that page, I didn't need to read anything else. Whereupon I closed the book and started the car.
A book will of course contain many topics. You must put these in the correct order, and you must create a suitable structure with chapters and sections. All this is done in one or more topic maps.
In DITA version 1.2, the following topic types are used:
Task topic
A task topic must contain a procedure. And only one. The procedure must explain how something is done, that is, how a task is performed.
Concept topic
A concept topic must contain a conceptual description, i.e. what something is, or how it works. The information should expand the reader's understanding when a procedure is to be carried out, or contribute information that is "important" for the reader.
Reference
A reference topic must also contain a conceptual description, but the topic is reserved for information of the "reference information" type. This is information that the reader "might" need, or that it is "nice to know". I like to say that this is information reserved for those readers who want to become "experts".
In DITA version 1.2, the following topic types are also available, but not so widely used:
Glossary topic
A glossary topic has a specialized structure to describe a word or phrase in a glossary.
Glossary group
A glossary group topic is a specialization that allows you to add many glossary topics to a group.
General Task
A general task topic must contain the same as a normal task topic, but the structure is looser. In many cases, the task topic is referred to as "strict task topic". The purpose of the general task topic is to make it easier to transfer information from sources other than DITA where the structure is not so strict.
Machinery Task
A machinery task topic must also contain a procedure. The difference from the others lies in the structure.
In DITA version 1.3 introduced a new topic type:
Troubleshooting
A troubleshooting topic contains a standardized structure for explaining troubleshooting
Creating a new DITA topic from a template
Creating a new DITA topic by duplicating an existing topic
Inserting a topic into a topic map
Inserting a topic into a bookmap
All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.
The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.