Topics

Topics

A topic is a file that contains textual information describing a single concept, procedure, or system component. Topic files have a .dita extension.

Within each topic there are elements and text.

  • The text is what your audience will read.
  • Elements contain the text, like boxes in a form. Elements can also contain other elements, like the sections of a form. Elements define the structure and meaning of the text. (Elements and stylesheets are also used to apply formatting to text during the publishing process.)

You can see the elements and text by showing element tags (View > Show Tags). Tags indicate the beginning and end of each element.

You can see just the text by hiding element tags (View > Show Tags). It's not exactly WYSIWYG, but it does give you an idea of what the topic will look like when published. Exactly how a topic will appear when published depends on your publishing process, which may be different for different output formats.

Elements still exist in this view, but element tags are not displayed.

There are several types of topics, and each type provides a different set of elements for structuring topic content. The most commonly used topic types are:

  • Concept topics provide background that helps readers understand essential information about a product, a task, a process, or any other conceptual or descriptive information.
  • Task topics answer the question "How do I?" by providing precise step-by-step instructions detailing the requirements that must be fulfilled, the actions that must be performed, and the order in which the actions must be performed.
  • Reference topics provide data in support of the performance of a task. Reference topics may provide lists and tables that include product specifications, parts lists, constraints on use or performance, software commands, and other data that is often "looked up" rather than memorized.
  • (Generic) Topics provide any type of information, and are typically used for information that is not strictly Concept, Task, or Reference, or when a high degree of content structure is not required.

In addition to elements that are specific to a certain topic type, many other elements can be used in any topic type.