DITA 1.3 is on the way!

Members of the OASIS Darwin Information Typing Architecture (DITA) TC [1] have recently approved a Special Majority Ballot [2] to advance Darwin Information Typing Architecture (DITA) Version 1.3 as a Candidate OASIS Standard (COS). The COS now enters a 60-day public review period in preparation for a member ballot to consider its approval as an OASIS Standard.

For more information, see https://www.oasis-open.org/news/announcements/60-day-public-review-for-dita-v1-3-cos01-ends-november-15th

My presentation from CMS/DITA NA 2015

In April, I had the honor and pleasure to present at the 2015 Content Management Strategies/DITA North America (CMS/DITA NA) in Chicago. Hosted by the Center for Information Development Management, CMS/DITA NA featured a program of more than 75 presentations regarding DITA.

My presentation was entitled DITA and S1000D: Two Paths to Structured Documentation. Today, the creation of usable technical documentation is accomplished through the managed authoring of quality content. Increasingly, that content is being created using structured data, in part due to its unique inherent advantages. The presentation compared the similarities and differences between two of the most popular XML-based structured data specifications that are being adopted by companies world-wide: DITA and S1000D.

I've placed the presentation on SlideShare. Feel free to take a look. If you have any questions, please don't hesitate to contact me.

And if you're interested, head over to the DITAWriter for Keith Schengili-Roberts' excellent Observations from DITA North America 2015 Part 1 and Part 2.

One Dataset--Multiple Documents

One of the most useful features in DITA is Conditional Processing (or Profiling), which allows you to use the same set of source files to create different versions of your documentation. Content is marked in a way that you can filter out entire topics, paragraphs, sentences, and even words.

DITA offers a set of standard profiling attributes that are applicable to most elements. Those attributes are:

• audience
• platform
• product
• props
• otherprops
• rev

Most of the names are self-explanatory. The props and otherprops attributes are meant to be generic for that you can use for any situation. The rev attribute is meant to identify material that was added or changed during a revision.

Let's take a look at how you could use these attributes to create different versions of a document.

Figure 1 is part of a sample topic for installing a product on either a Windows or a UNIX operating system.

Figure 1.

Figure 2 is the source material for the topic.

Figure 2

Your project manager tells you that you have customers that are only interested in Windows and some that are only interested in UNIX. Add into that pot folks that are using both Windows and UNIX.  Which of those profiling attributes are you going to use?  You got it, platform!

Figure 3 is how you have tagged the source to create docs for each set of customers.

Figure 3

For the customer that is interested in both Windows and UNIX, you added a platform attribute called all. Then you added an info section with only the Windows information and tagged it with a platform attribute called windows. And finally, you added platform attribute called unix for the the UNIX customers. Now, how do you get those marked sections to show itself or to hide. The answer is to create a ditaval file.

A ditaval file is used to instruct the transform what to do with your conditional attributes. Figure 4 is the ditaval file I created for the topic.

Figure 4

In this ditaval file, only the platform values of all will be displayed. So you would get a topic just like Figure 1 after your transform is completed. If you want to display only the Windows platform, you would edit your ditaval file as shown in Figure 5.

Figure 5

The resulting topic after you transform is shown in Figure 6.

Figure 6

And you would do the similar to create a UNIX only topic.

Now your project manager tells you that your customers want separate documentation for novice and experienced users. So you take a look at your documentation and decide that an experienced user wouldn't need to be told what the variables (x and license_filename.lic) mean. In this case, you would use the audience attribute on selected paragraphs as in Figure 7.

Figure 7.

Paragraphs that only a novice would be interested in are marked with an audience attribute called novice. Before you transform, you need to add the attribute to your ditaval file as seen in Figure 8.

Figure 8

The ditaval instructions now read to include platform attributes called windows, exclude platform attributes called unix and all, and exclude audience attributes called novice. After you transform, you get the topic seen in Figure 9.

Figure 9

We're not done yet. Now your project manager tells you that have a customer that thinks desktops are history. Therefore, they want only references to the laptop. The offending word is in your short description. Do you want to create two short descriptions and label them with appropriate attributes? You could. Or you could attack the offending words directly using the <ph> tag and the props attribute as seen in Figure 10.

Figure 10.

Note that the word or is also tagged. If it isn't excluded also, the sentence will not make sense.

Now you add the attribute to your ditaval file as in Figure 11.

Figure 11

The ditaval file instructions read to:

• include platform attributes called windows,
• exclude platform attributes called unix and all,
• exclude audience attributes called novice, 
• and exclude props attributes called desktop.

This results in the topic seen in Figure 12.

Figure 12

Summary

We only took a look at the platform, audience, and props attributes in this post. I think you get the idea though.

DITA's conditional processing is a powerful and useful feature.

Write the right short description

In earlier posts, I discussed the importance of the short description <shortdesc> element (Big rewards for a short description) and best practices for writing the descriptions (Best practices for the short description element). This post discusses the importance of tailoring your short description for the type of topic you are writing.

A short description is short overview of the topic including why it matters. DITA topics are one of the following types:

• Task
• Concept
• Reference

 

Task topics

A task topic is intended for a procedure that describes how to accomplish a task. A task topic lists a series of steps that users follow to produce an intended outcome. So a short description for a task topic should explain to the reader the purpose of the task. It can be helpful for a user to know why a task should (or must) be performed. For example, the following sentence doesn't explain why you would want to configure security settings.

Use this procedure to configure security settings for the ABC product.

Perhaps it is obvious to you, but don't take that for granted. The following sentence is an effective rewrite.

Security settings determine who can and cannot use the ABC product.

When you understand the benefits of the task writing, the short description is easier.

 

Concept topics

A concept topic is more objective, containing definitions, rules, and guidelines. So a short description for a concept topic should answer the questions "What is the concept and why should users care?" Therefore, you will want to clearly define the concept, which could be a feature, technology, or tool. Explain also why users should understand this information. The following is a poor short description for a concept topic.

This topic covers fuel filters.

Why should the user read about fuel filters? What are fuel filters? Are fuel filters important to me? The following rewrite explains all of that.

Fuel injector units require cleaner fuel. Fuel filters screen out dirt and rust particles from the fuel.

Reference topics

A reference topic describes command syntax, programming instructions, and other reference material, and usually contains detailed, factual material. Short descriptions for reference topics should explain what an object does, how it works, and why is it useful.

The chdir command is used in directories.

OK. How is it used? Why is it used? The following short description answers that and more.

Displays the name of the current directory or changes the current folder. Used with only a drive letter (for example, chdir C:), chdir displays the names of the current drive and folder. Used without parameters, chdir displays the current drive and directory.

 

Converted topics

 The previous information helps when you are creating your topics from scratch. But what if you have converted existing documentation from another format to DITA? The temptation is to  move the first sentence or paragraph to the <shortdesc> element, or to simply not use the short description at all. As explained in a previous post (Big rewards for a short description), this can harm the quality of your document.

Evaluate your first paragraph. You will likely have to rewrite the first sentence or paragraph to make an effective short description.