What is Reference Topic Type in DITA XML?

[Jordan_Stanchev]

If you are a technical writer and want to create and manage your documents quickly and efficiently, then DITA XML is for you. This blog post provides an overview of DITA XML and how you can use it in your technical writing. It also explains the most-popular topic types, including the Reference topic type that many authors fail to grasp completely. 

But first, let's address some fundamental questions: 

What is DITA XML?

Darwin Information Typing Architecture (DITA) is an open standard. DITA describes the architecture for creating and managing information that separates content from formatting. This separation enables streamlined content creation and straightforward ways of publishing for new technologies such as mobile devices.

DITA XML is optimized to create, reuse, translate, and publish documentation quickly, using topics and maps.

IBM launched the first version of DITA in 2001, and it is currently maintained by Oasis after its donation by IBM as an open-source architecture. The current version of DITA is 1.3, which was approved in 2015.

What are the benefits of writing in DITA XML?

DITA is a way to use your content as an asset, a method that is not possible in other content-creating tools like Word, WordPress, Wiki, etc. DITA enables you to reuse, manage, translate, and publish your documents.
DITA takes advantage of XML (eXtensible Markup Language) to make your content intelligent, versatile, manageable, and portable. DITA content can be easily converted into other formats such as Word or HTML, easing the content creation process and improving the overall quality of your documents.

Technical writers originally used DITA to create complex communication content, like manuals and user guides but its use is spreading to other fields such as:

• Business writing
• Portfolios
• Marketing
• Training and teaching

There are no limits to DITA's benefits, and as a technical writer, DITA XML will save you time and money.

What is a Topic?

As per the DITA specification, when you write and provide information, you structure and organize it using various standardized XML elements organized into one single entity - a Topic. 

What is Structured Writing or Topic-Based Writing?

You apply structured writing as a technical writer. Structured writing means that you write in a manner that allows you to organize the information following a pattern. Of course, this makes sense only when the type of information you write is of the same kind.

For example, let's assume you have to write software documentation. This documentation instructs your reader on the steps they need to perform to install the software application. But, the instructions are long and complicated, comprising hundreds of steps and variations of these steps.

How can you make it easier for the customer to follow while reducing the potential errors that the user might make?

Well, what you can do, is make sure that you break down the complicated instructions into short and concise steps. You create these steps with a clear definition of their objective, that is, the result that the reader expects to achieve once all steps are done correctly.

You also want to ensure that you organize all parts of the instruction in the same way - this makes it easier for the reader to focus on the content and reduce the chance that they miss important information.

The DITA XML template for this is the Task template.

What if your user needs to understand a specific concept or architecture to properly perform the task? Instead of trying to squeeze such information inside your Task topic, you position it as a separate topic, focused only on this conceptual type of information.

The DITA XML template for this is the Concept template.

So far we've described tasks and concepts. This is great information from the standpoint of a new user that needs to know the steps to follow and the architectural background. But what about a user who is already familiar with the steps? He or she has performed them a hundred times - how do you help such a user with the documentation?

After all, the user needs only the input parameter information to cross-check while following the installation steps, right? What the reader wants is simply the list of items to go through and nothing else.

Obviously, such information does not fall under the category of Task or Concept.

You still need a place to put your checklists, tables with reference values, lists of items or properties, etc.

The DITA XML template for this is the Reference template.

The DITA Specification 1.3 provides the following definition of Reference topics:

"Reference topics are specialized from topic. They contain the standard topic elements, including title, short descriptions or abstract, a prolog, a body, and related links."

So, what is a reference topic?

Reference topics provide data that supports users as they perform a task. Reference topics might provide lists and tables that include product specifications, parts lists, and other data that is often looked up rather than memorized. A reference topic also can describe commands in a programming language or required tools for a series of maintenance tasks.

Reference topics provide quick access to fact-based information. In technical writing, reference topics are used to list product specifications and parameters, provide essential data, and provide detailed information on subjects such as commands in a programming language. Reference topics can contain any subject matter that has regular content, such as ingredients in recipes, bibliographic lists, or catalog items.

The top-level element for a reference topic is the <reference> element.

The refbody element contains the main body-level elements of the reference topic. Reference topics limit the body to tables (both simple and complex), property lists, syntax sections, generic sections, and examples.

All of the elements of refbody are optional; they can appear in any sequence and number.

So, as you can see, DITA and the common DITA Topic types already offer us, the writers, a lot of flexibility in structuring and organizing the information. This leads to better usability of the content for readers, lowers the learning curve for them, and this way puts us in control of the information architecture of the documentation. 

In the comments section below, I'd be happy if you share with me and the readers of this blog more about how you use DITA to influence the user experience.