If you are a technical writer, trying to understand the definition of the Reference topic type used in DITA XML, then this blog post is for you.

What is a Topic?

As per the DITA specification when you write and provide information, you structure and organize it using various standardized templates. DITA refers to these templates as Topics.

What is Structured Writing or Topic-Based Writing?

You apply structured writing as a technical writer. Structured writing literally means that you write in a manner that allows you to organize the information following one and the same pattern in your writing. 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 will instruct your read on the steps he or she needs to perform to install the software application.

But the instruction is long and complicated. It literally comprises hundreds of steps and variations of these steps.

What can you do to make it easier for the customer to follow, on the one hand, and reduce the number of errors that the reader accidentally performs?

Well, what you can do, is to make sure that you break down the long and complicated instruction in short and concise steps. You make these steps with a clear definition of the objectives of the steps, the result that the reader will achieve once all steps are done correctly.

You would also want to make sure that all of the parts of the instruction are organized in one and the same way - this will make it easier for the reader to focus on the content and reduce the possibility to miss important information - simply because it is always organized in the same pattern.

The template that you will follow in case you write using DITA XML is called Task.

What is 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 would position it as a separate topic, focused only on this conceptual type of information.

The template that you will follow in case you write using DITA XML is called Concept.

OK. So far we've described steps and concepts. It is great information from the standpoint of a new user that needs to know the steps to follow and the architecture 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 parameters 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 template that you will follow in case you write using DITA XML is called Reference.

As per definitions, the DITA Specification 1.3 provides the following definition of Reference:

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

Purpose of the 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 information, reference topics are used to list product specifications and parameters, provide essential data, and provide detailed information on subjects such as the commands in a programming language. Reference topics can contain any subject matter that has regular content, such as ingredients for food in recipes, bibliographic lists, catalog items, and so on.

The structure of the reference topic

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."

I talk about these items also in my latest course on DITA XML that comes with free access till April 15. Feel free to check it out here: https://www.udemy.com/course/technical-writing-common-dita-xml-map-and-topic-elements/?couponCode=FREE-START