Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Topics
FrameMaker (a standard documentation tool) and other XML-based solutions such as DocBook use the traditional, fairly rigid book-chapter-section metaphor—the book is a container that contains chapters, which in turn contains individual sections describing an idea or a task. DITA, on the other hand, is based on topics. Topics are small pieces of information on a single subject. But a topic is just a container that can hold the following elements (called information types in DITA lingo):
- Concepts are background or conceptual information.
- Tasks are procedures that explain how to do something.
- References are more specialized information, or information that’s intended for a highly technical audience; for example, code documentation for software developers.
Following is an example of a simple DITA topic:
<title>A DITA topic</title> <titlealts> <searchtitle>This is a DITA topic</searchtitle> </titlealts> <shortdesc>This is a brief description of a DITA topic.</shortdesc> <prolog> <author>Scott Nesbitt</author> </prolog> <body> <p>A topic must have both a title and body.</p> </body> <topic id="main"> <title>A really short topic</title> <body> <p>This is a really short topic. It only contains this text, along with a title.</p> </body> </topic> </topic>
Topics can consist of entire sections of a chapter, a single paragraph, or just a list. They’re chunks of information that can be taken and fit together as needed, as if they were Lego blocks. This arrangement gives writers almost unlimited flexibility with what they write and how they combine topics.
Topics are combined using topic maps. A topic map is like a table of contents in a book. It spells out which topics are included in a particular document, and how those topics are organized. Following is an example of a DITA topic map:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "../dtd/map.dtd"> <map title="Example DITA Topic Map"> <topicref href="topics/editphotss_overview.xml" type="concept"> <topicref href="topics/opening_photos.xml" type="task"/> <topicref href="topics/cropping_photos.xml" type="task"/> <topicref href="topics/applying_effects.xml" type="task"/> <topicref href="topics/removing_redeye.xml" type="task"/> <topicref href="topics/airbrushing.xml" type="task"/> </topicref> </map>
Another aspect of DITA is the domain. A domain defines the elements and tags that enable writers to mark up documentation on a specific subject. For example, there are domains for the elements that are used to mark up the descriptions of user interfaces and software, or examples of programming code.