Working with DITA Topics
DITA is a structured writing format. Structure can have several meanings, all of which are relevant to DITA. This section includes information about working with DITA topics and the structure.
Information Types
The structure of a piece of content refers to how the words and images are selected and organized to convey information. One approach to structured writing is to divide content into discrete blocks that contain various types of information, and then to combine those blocks to form publications. DITA is based on this approach, and encourages the author to write in discrete blocks called topics. DITA provides three base topic types (concept, task, and reference), a number of extended topic types, and the capability to create new topic types through specialization.
Text Structure
Every piece of text is made up of certain text structures, such as paragraphs, lists, and
tables. DITA supports text structures through XML elements such as <p>,
<ol>, and <simpletable>. The DITA
markup specifies the text structures, but not how they will be published in various
types of media. The formatting of text structures is determined by the output
transformations and may be customized to meet the needs of various organizations and type of
media.
Semantic Structure
- A
<task>element specifies that a block of content contains the description of a task. - A
<codeblock>element specifies that a block of text consists of programming code. - A
<uicontrol>element specifies that a word is the name of a control in a computer GUI. - The
@platformprofiling attribute specifies that a particular piece of content applies only to certain computing platforms.
Semantic structure is important in a structured writing system because it allows both authors and readers to find content, and it allows processing scripts to process various pieces of content differently, based on their role or meaning. This can be used to do things such as filtering content related to a specific product so that you can produce documentation on many products from the same source.
There can be many forms of semantics captured in a document set. DITA captures some of these in topics and some of them in maps. If you are using a CMS, it may capture additional semantics.
Document Semantics
Documents consist of elements that may be made up of the same basic text structures as the rest of the text, but have a special function within the structure of the document. For instance, both tables of contents and indexes are lists, but they play a special role in the document. Chapters and sections are just sequences of paragraphs and other text structures, yet they are meaningful in the structure of the document. In some cases, such as indexes and tables of contents, these structures can be generated from semantic information embedded in the source. For instance, a table of contents can be built by reading the titles of chapters and sections. DITA provides elements to describe common document semantics.
Subject Matter Semantics
In some cases, the semantics of the content relate directly to the subject matter that the
content describes. For instance, DITA supports tags that allow you to mark a piece of text
as the name of a window in a software application (<wintitle>), or to
mark a piece of text as applying only to a particular product.
Audience Semantics
In some cases, the semantics of the content relate to the audience that it is addressed to.
For instance, a topic might be addressed to a particular role, or to a person with a
particular level of experience. DITA provides an <audience> element
to capture audience metadata.
Creating Topic Structures
- Content Completion Assistant - Shows you which elements can be created at the current position.
- Model view - Shows you the complete structure supported by the current element.
- Outline view - Shows you the current structure of your document.
- DITA toolbar - Helps you to easily insert many common structures.
Resources
For more information about getting started with DITA and how to work with DITA in Oxygen XML Editor Eclipse plugin, see our compiled collection of DITA-related webinars that are meant to help you with your journey into working with DITA: Webinars: Working with DITA in Oxygen.