One very important characteristic of a technical writer is being able to write very specifically. Without flowery language and in a way that offers an immediate guide to developers, other technical writers, or the general public who would consume your information.

There are writing tools meant for writing software documentation in a way that properly guides the author in structuring the information to be delivered. One of such tools is DITA. Read on to learn about DITA.

Darwin Information Typing Architecture (DITA) is an XML-based data model writing tool that is meant to structure and organize documents in a very specific way. It is used for authoring and publishing purposes in different formats based on how the targeted audience will consume it.

DITA is run by an Oasis Technical Committee and it comprises technical committee participants including IBM, Dell, Adobe Systems, Microsoft, Cisco Systems, and others.

There are many parts of DITA specification but for this article, we'll focus on DITA markup. DITA markup is divided into 3 parts, namely:

• DITA maps

• DITA topics

• Subject scheme maps

• The DITA maps allow you to properly organize and structure the information you have into simple contents. It guides the author on the path to follow before writing. This is done outside of the actual contents to be written and it is the first step in structuring the information. It helps to organize the topics and content.

• The DITA topics allow you to have structured writing. Each particular topic contains one single subject. The topics are usually of a specialized information type. Some information types are concept, procedure, process, concept, and reference with the most commonly used being;

• Concept

• Task

• Reference.

The concept information type seeks to describe the idea behind a certain operation. It shows how a thing works, the action behind it, and the way around it. This is usually meant for people who do not understand how a particular thing functions and are trying to understand its dynamics of it.

Task information type distinctly tells the step-by-step action that leads to a certain result. The essence of task information type is to show the consecutive procedures that give an intended result. It should be written in a way that the end-user can follow step by step to solve the problem.

Reference information helps to give detailed material to people who are already knowledgeable on the subject matter but need more information to validate and check for what they already know. These people are already familiar with the concept but might need some pointers.

• Subject scheme maps allow you to define specific keys and metadata needed to classify the content. It helps to define the metadata and provide meaningful information about the content in the documentation.

Writing in DITA

When writing in DITA, there are some important points to take note of. These points will guide you on how to structure your document in acceptable ways.

Writing based on information type

As a technical writer, the majority of the content written will be based on information type and most of these information types will be on a concept, task, and reference. Task information type will usually be the most written content among all 3. Task information involves writing specific instructions provided for users for them to get a particular result. The concept should provide information on the background of the subject matter. And the reference information should provide the user with details of the subject matter. These information types are intended to solve an immediate difficulty for the end-user.

The structure of the content will be organized using maps

It is worthy of note that DITA does not give room for unnecessary statements. There is a predetermined structure that defines what will be included in the final deliverable. This structure is done outside of the content by the DITA map system. The deliverable structure and organization are different from the actual content deliverable.

DITA enforces strict rules for writing

Software documentation is not meant to be read as a book during leisure or for entertainment. It is meant to provide an immediate solution to the problem of the end-user. And it is for this reason DITA ensures that there are firm writing rules to allow only the most needed information. The content should be structured in a way that the end-user can follow in a logical way to solve their problem.

The contents should be written in modules to allow for reuse

The entire information should be broken down into smaller modules and free of context so it can be reused in entirely different documentation. A small section of the initial document may be needed in an entire document. So breaking the documentation into smaller modules allows for reuse in other documentation without needing to be altered. That is one of the implications of writing in DITA, modularized and reusable.

Final word

Structured writing helps to create a structured, straightforward, and easily applicable document. If you've been writing in an unstructured environment, it might take a while to adjust to a structured environment such as DITA. But it is the best way to write information that needs to convey a central idea. Structured writing also serves the customers well for a much easier application of the solution as well as saves the time of the author.