Technical Writing and DITA
Companies that produce technical documents face a market that is constantly evolving as new technologies become available. In the past, a product might require only a single manual. Consumers are now able to access information in many different forms, including websites, support forums, knowledge base systems, FAQs, and many more. DITA can help writers to meet the challenges of producing technical documents in an increasingly complex global market.
What is DITA?
DITA, or Darwin Information Typing Architecture, is an XML-based system for creating and publishing topic-based content. In 2005, DITA was adopted by OASIS (Organization for the Advancement of Structured Information Standards) as a standard. The OASIS DITA Technical Committee is now responsible for maintaining and updating DITA.
The base feature of DITA is the use of special information types in the form of topics. The DITA language includes both generic topics and specialized topic types, including concept topics, reference topics, and task topics.
Why use topics as the base for DITA? Technical documents such as HTML Help (chm) and browser-based help have a very different structure from books. Traditional book structure includes chapters, sections, and subsections. Authors usually use applications such as Word to create this book type structure. But this structure often doesn't meet the needs of technical content that may be needed in different outputs and for different audiences.DITA supports a number of features that are very useful for writers of technical documentation. Below are the primary features of DITA.
DITA supports a single source that can output multiple formats
Recent years have seen many changes in the methods of delivering information to users. In the past, an application or product might have a single manual or user guide. Now user guides can be delivered in many different ways such as Web, HTML Help, PDF, etc. DITA allows you to produce outputs in several formats from a single set of XML files. For example, you can produce an HTML Help file, a PDF file, and HTML files all from a single source.
DITA is topic-based
The primary feature of DITA is the organization of information into individual topics. The topic-based structure allows the writer to organize content into individual chunks of information. A topic is usually a single task, concept, or reference.
Below are some of the advantages of organizing content into topics:
- Help to promote consistency
- Allow writers to focus on individual tasks or concepts
- Can be easier to localize
- Facilitate the production of multiple outputs from one source
DITA promotes re-use
By organizing content into small chunks, it is much easier to re-use content for multiple outputs. When content is structured this way, it becomes possible to freely mix-and-match the content so that it can suit the needs of different users.
DITA also allows the writer to set conditions for the audience, products, version, and platforms. The writer can then use these conditions to produce different outputs for different types of users.
You may need to write a help system for a software application that is available in both PC and Mac versions. The functionality of the application is similar in both operating systems, but there are a few differences between the PC and Mac versions. By using the platform attribute, you can indicate which operating system the topic covers. You can then create two topic maps – one for PC and one for Mac – and produce documentation for both operating systems.
DITA allows specialization
While DITA comes with a set of pre-defined elements, it also offers the ability to customize document structures for specific uses. Specialization is a process where you define new elements and attributes that are based on existing DITA elements.
Example of specialization
You might be writing a document that describes a recipe collection. A topic-based structure is suitable for a recipe collection since each recipe can be contained within a separate topic. If you wanted to create a specialization for the recipe, you could create a new element recipetopic that uses the topic element as a base.
In looking at the structure of the topic element, you might decide that you need a new element, ingredients, in the recipetopic element. You can then create a new element ingredients that uses the ul (bullet list) element as a base. By using specializations of existing DITA topics, you are easily able to create new elements.
This ability to extend the base elements to other types of documents makes DITA a flexible system that can adapt to the needs of different documentation projects.
DITA separates content from formatting
The formatting of the content is in a separate file from the content. This allows the writer to focus on writing content rather than focusing on the formatting of the content. Since the formatting lies in separate files, the output will be consistent, even when there are multiple writers.
DITA reduces translation costs
By maintaining content in one source, it is easier to manage translation costs. For example, if you have one procedure that is used in several types of content (web site, HTML Help, FAQs), then you need to translate only one document rather than three documents.
Looking ahead
Single source technologies such as DITA will allow technical writers to use standard processes for creating and publishing technical content. These processes will help writers to be more efficient in meeting the complex documentation needs of the today and the future.
About the author
Susan Bodnik is an online education instructor and instructor coordinator at Online-learning.com. She holds a degree in English from the University of Waterloo with special research in communications, rhetoric and online learning. She maintains an active interest in evolving technologies related to online education and XML. Susan is involved in all aspects of course development, quality assurance, delivery and evaluation. Susan is currently working on an online course on DITA, which will be available soon. Contact us for details.