DITA Terms and Their Plain Language Meanings

TechWhirl's DITA articles and resources are brought to you by easyDITA. Learn more about their product & sign-up for a free trial at easydita.com.

DITA-Darwin Information Typing ArchitectureDITA is often seen by technical communicators as hard to understand, which may be due to unfamiliarity with the terms. This chart of DITA terms can help you make sense of DITA, whether you’re brand new to the area, or a veteran. If during your work, you run across a term that doesn’t appear in the chart, drop us a note, and we’ll be happy to add it.

DITA Term

Plain Language Term

Description

Attribute Descriptor The characteristics of an element that are attached to it when it is included in the markup. An attribute has two parts: a name and a value.For example the <note> element can have a type attribute and value set it to tip: <note type=”tip”></note>
CCMS Database A specialized database that can store DITA files (or other content). A component content management system (CCMS) makes finding, authoring, reviewing, publishing, and translating content easier.
Chunk Split into topics The process of breaking long pieces of content, like a chapter, into shorter, self-contained topics that can be assembled and reused.
Concept topic Explanation A DITA core topic type that is written to provide notional or background information on an idea, theory, model or hypothesis to improve their understanding of the subject matter.
DITA Content model Darwin Information Typing Architecture (DITA) is an XML standard that is useful for producing documentation of any kind.
DITAMap Collection or book A file that collects topics together in a specific order and hierarchy, and is most often used to create a deliverable or library of content.
DITAval file Filtering mechanism A mechanism that filters or flags content marked up with specific attributes.For example, a DITAval file could hide any elements that have the attribute value product=”Oranges” applied, so when the author publishes content for the Apples product, no Oranges content displays.
DITA adoption Process of moving writers into working with DITA The entire process of moving an organization from content production without DITA to using DITA. DITA adoption includes content strategy, planning, DITA conversion, training, tool selection, publishing, change management, project management, and many other facets.
DITA conversion Structuring content A set of activities focused on moving existing content from an unstructured (or other structured) format into DITA topics and maps, applying appropriate elements and attributes to the content.
DITA OT Publishing toolkit A set of files that provide default publishing from DITA XML into a variety of outputs like PDF and HTML.The DITA OpenToolkit is free. It is maintained and updated by volunteers.
Element Tags A bracketed label that contains information and indicates what kind of information it is. Every element has an opening tag and a closing tag.For example a <cmd></cmd> element would contain content designated as a command for the user to follow, like <cmd>Log in to your system.</cmd>
Glossary topic Glossary term and definition A topic that includes at least two things: a term and a definition for that term. A glossary topic may also include abbreviations, synonyms, and all the other pieces of information that support a dictionary or glossary term. Not every documentation set needs glossary terms.Some common ways to use glossary topics:

1. Create an appendix with all terms and definitions in an alphabetized list.

2. Provide inline popups over terms that need a definition (e.g., in a task, the word “Disambiguation” has a hover hyperlink to provides a definition when the user places their cursor over that word).

3. Provide a link from the inline term to the glossary definition.

Linking Relationships between topics One of several methods of connecting two or more pieces of content together, allowing users to quickly navigate to related content, or authors to reuse existing content where needed.Some of the linking mechanisms include relationship tables, cross references, content references, and keys.
Metadata Information about the content Information about information. In the DITA context, metadata refers to information about the content.For example, an attribute and its value are metadata about an element.
Minimalism Clear, targeted writing An approach to writing that focuses on providing the right type and amount of information in the right location for people to use effectively. Minimalism’s goal is to target and streamline content for quick retrieval and consumption.Only one aspect of minimalism includes removing extraneous words.

Although not strictly part of DITA, minimalism is often used in conjunction with DITA because the result is clear, usable content.

Reference topic Quick look up A DITA core topic type that is meant for quick look up, like a table of keyboard shortcuts.
Reuse Using the same physical piece of content in more than one spot Approach that allows authors to write content once and use it in more than one1. place in a document, or

2. place in many documents

Forget copy and pasting content: DITA lets you reuse it instead. From a phrase or term to an entire set of topics, the level of reuse is up to you.

Semantic markup Content has meaningful tags applied Tagging applied to a piece of content that indicates the context of the information, or what type of information it is.For example, the title of a topic would appear in a <title> element (remember, there’s no formatting in XML) and the information that tells the user why they would perform a task is in a <context> element.

Once you have the appropriate tags around the appropriate content, you have applied semantic markup and can then apply formatting to all <title> elements, for example, with one formatting transform rule.

Single sourcing Multichannel publishing The process of compiling a set of content topics and producing many different output types, such as PDF, HTML, and Excel.
Structured authoring Tagging content The process of writing content and applying a semantic markup, such as DITA tags.Some people mistakenly think structured authoring means that it adds organization to their content. This is true, but does not adequately describe the full meaning of structured authoring. Organization is only a small part of it.

For example, a <context> element is only allowed in one spot: right before the steps of a task. You can’t have it after the steps or in between them. Thus, you enforce a consistent structure of your content and it’s better organized as a result.

Tag abuse Applying semantic markup badly Occurs when an author uses an element that does not match the type of content contained within the tag, which defeats the purpose of semantic markup.For example, if someone wanted a context to display after a series of steps, they could use a <result> element, which is allowed after steps. However, then the content (a context) would no longer match the element that is used (a result).

Tag abuse is particularly prevalent with writers new to DITA, where they’re just trying to find any allowed tag in the spot they want.

Task topic Procedure A DITA core topic type that is written to help a user accomplish a specific goal, rather than provide general information.
Topic Page, section, or chunk A self-contained piece of content that has a title and some content. DITA includes three core topic types: task, concept, and reference.Other related topics include glossary and troubleshooting, as well as an entire set of topics specific to learning and training.
Topic-based writing Chunked content The process of writing (or re-writing) content that is appropriately chunked into a standalone piece of content, and specifically one of task, concept, or reference. Unlike narrative-based writing, topic based writing produces smaller, self-contained pieces of content.
Unstructured authoring Content not in XML Writing content without tagging it with semantic markup in XML. This includes anything written in Word, FrameMaker (unstructured), InDesign, or text editors.Note: Although Word 2010 (and later) creates an automatic XML file in the background (the “x” in .docx), it is poor quality XML and does not adequately structure any content.

This article and all TechWhirl articles on DITA are brought to you by easyDITA, the all-in-one DITA authoring and content management solution at easydita.com.

Jacquie Samuels

Jacquie Samuels is the owner of Writing Wise. She endeavors to help everyone create documentation that is stronger, faster, and smarter. You can connect with Jacquie through her Google Plus page.

Read more articles from Jacquie Samuels Twitter

Try Doc-To-Help Today