Skriftlig Info ➜ DITA publishing ➜ DITA topics ➜ Topic content and structure
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.
DITA topics are closely related to the methodology knows as "Topic-based authoring":
In technical documentation, the term topic-based authoring is used for a methodology where the content of a publication is structured in independent topics. Topics can be used in any order within a given publication and reused in other publications. The text in each topic should not assume that other topics are known to the reader and should not relate to others. Context is achieved by publishing different topics in a given order, preferably linked with hyperlinks.
Read it again: "A topic shall contain information that makes sense of its own." What does that mean?
Let's say you have a question related to a product you have bought. The product came with a printed instruction manual. The manual presents all the descriptions and instructions for the product. One of the pages contains a complete section. This section is a topic with a title, and the topic provides information related to the title.
The instruction manual is big, and you are in a hurry. To save time, you rip the page out of the book.
When you sit down to read the information on the page you tore out, it makes sense to you. The information on the page fulfils the expectations the title gave you and answers your initial question. You realize that to solve your immediate issue, you don't need to read the rest of the book. The topic contained the specific information you were looking for.
You have bought a digital camera. You need to find out how to insert the battery.
The instruction manual contains a section called "Inserting the battery". It is located on page 244.
You open the book on page 144 and read the instructions.
Everything you need to know is there. It is all provided in that single task topic.
You can close the book.
You have just bought a pre-owned TV, but it is something wrong with it. You need to find someone to fix it.
The instruction manual contains a section called "Service and repair". It is located on page 25.
You open the book on page 25 and find a complete list of repair shops. The list is complete with names, addresses and relevant contact information.
Everything you need to know is there. It is all provided in that single conceptual topic.
You can close the book.
Your partner has bought a costly kitchen utility. It is provided with lots of extra parts and gadgets. One of these gadgets catches your attention, but you need help to understand what it is used for.
The instruction manual contains a section called "Additional equipment". It is located on page 56.
You open the book on page 56 and find an illustration. The illustration identifies each part and presents a short description of its use. References are made to detailed descriptions and operating instructions.
Everything you need to know is there. It is all provided in that single conceptual topic.
You can close the book.
Your lawnmower has stopped, and you have brought it into the garage to fix it. You realize that you need to replace a specific part.
The instruction manual contains a section called "Spare parts". It is located on page 76.
You open the book on page 76 and find an illustration that identifies the main parts of the lawnmower. For each part, a reference is made to a dedicated spare part section. You can easily locate the part you need to replace and open the relevant page. All necessary information is there, such as an illustration, the part's name and order number. There is even a link to a website that lists all the dealers that can sell you the part.
Everything you need to know is there. It is all provided in that single spare part topic.
You can close the book.
You have bought a new software program for your home computer, but one of the dialogue boxes is hard to understand. It offers many parameters that are far from intuitive.
You select the Help button to open the context-sensitive online help. It opens a page that explains all the functionality that the dialogue box offers, even with links to related tasks.
Everything you need to know is there. It is all provided in that single reference topic.
You can close the online help.
In the first examples, I have referred to a traditional printed instruction manual. The information may, of course, be available on any media, including an interactive electronic technical manual (IETM).
|
The basic idea of topic-based authoring is that you collect all your information in topics that all "make sense of their own". Using these topics, you can assemble a complete manual by placing the topics in any order and structure that fits your purpose. |
Once you have made these topics, you can also use them repeatedly in many manuals.
|
DITA is all about sharing and reuse. If you create great topics, you can use the functionality DITA offers to reuse them in many publications. You can also reuse the topics created by your colleagues, just as they can reuse the topics you make. In the end, you are able to save time and money. |
A topic has a flat structure. It has a title, a short introduction, and then the necessary multimodal text. Depending on how your style sheet is created, the title is included in the table of contents when you publish your book.
It is not possible to create titles within a topic and place these in the table of contents. You can't do this because you can't create a "sub-structure" within the topic. You can still add sections, and each section can have a title. The purpose of such titles is to divide the information into chunks of text that are easier to read.
This very page you are reading right now uses the same structure. This page has a title and several separate sections with individual titles. These section titles are not shown in the list of pages.
The sections and section titles are not mandatory. You decide how to use these in your concept and reference topics. Task topics have a different structure, so these will normally contain section titles. Still, you will always be in charge - unless your style sheet dictates otherwise.
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.