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.

Best practices for the short description element

In my previous post (Big rewards for a short description), I talked about the importance of the short description <shortdesc> element. Effective short descriptions are an opportunity to help users easily find the correct information for which they are looking. Keep the following best practices in mind when writing your short descriptions.

Do not use cross-references within the <shortdesc> element

"Wait a minute," you say. "I tried to do that, and DITA won't allow it."  Yes, that's true. But, there is a fairly simple hack that allows you to include a cross-reference. Why shouldn't you use the hack? Let's go back to the intended use of the <shortdesc> element. To quote the DITA 1.2 Specification, "The short description, which represents the purpose or theme of the topic, is also intended to be used as a link preview and for searching." In other words, the short description is a synopsis of the topic. Using a cross-reference to another topic makes no sense. Put the cross-reference somewhere in the text of the topic or in a related topics section.

Consistently use a <shortdesc> element

The <shortdesc> element isn't mandatory.  If you want a quality document, however, you should make it mandatory. See my previous post on the rewards you can get from using short descriptions. If you have topics nested in your main topic, those topic titles are are automatically generated as links at the end of the main topic. (In DITA, the main topic is listed as the parent topic and the nested topics are the child topics.)  Under the topic title is the text in the <shortdesc> element. If you use short descriptions in some topics and not in others, the previews for child topic links will appear incongruous. And your readers could lose confidence in your document.

Have you got any best practices that your team follows? Please share if you do.

Big rewards for a short description

Writing text for the <shortdesc> element is easy. Writing good text for the <shortdesc> tag is hard. And if you don't write good text, you are doing your readers and your document a disservice.

The <shortdesc> element is usually one sentence. Sometimes two or more. But your editors will tell you to keep it short. Its name is what it is supposed to be. That is, a short description of the topic it is introducing.

The <shortdesc> element is common to all DITA types of topics: Concept, Task, and Reference. It is the first paragraph in a topic. However, it isn't mandatory. You can eliminate the element and you will still have a valid DITA document.

So why use it?

A colleague of mine, Don Day, wrote "... of all the DITA elements, shortdesc is most like a credit card with a loyalty program that rewards you for using it."

What kind of rewards does the <shortdesc> element provide? Very simply, it allows readers to easily find the correct information for which they are looking.

 Easy to find

In Developing Quality Technical Information: A Handbook for Writers and Editors, the authors identify nine characteristics that quality information shares. These characteristics are further grouped under:

• Easy to use
• Easy to understand
• Easy to find

If a reader can't find information they need to use product, they can become frustrated. And most likely, frustrated readers become disenchanted users. And that leads to bad product reviews. To avoid that road, take some time with your <shortdesc> element.

• The first paragraph
  
  Since it is the first paragraph in a topic, a well-written short description will tell the reader if it contains the information for which they are looking. A well written short description will contain keywords that will help the reader identify whether the topic contains useful information. It should be a concise description of the topic.
  Here's an example of a bad short description for a topic called "Introduction to Bird Calling" in documentation for the Acme Bird Feeder.
  
  The following topic contains instructions on how to master bird calling. 
  
  After reading the topic, the reader thinks "Why should I care about bird calling? All I want to do is feed the birds."
  
  When the short description is rewritten, the reader is given more information.
   
  If you wish to attract more birds to your Acme Bird Feeder, learn the art of bird calling. Bird calling is an efficient way to alert more birds to the presence of your bird feeder.
  
  "Ah," says the reader. "This topic will ensure that that I alert the birds that dinner is served! I'm getting the most bang for the bucks I put out for this bird feeder. The Acme Corporation has earned my loyalty!"
  
• Preview for links in online documents
  
  If you have topics nested in your main topic, those topic titles are are automatically generated as links at the end of the main topic. (In DITA, the main topic is listed as the parent topic and the nested topics are the child topics.)  Under the topic title is the text in the <shortdesc> element.
  
  A link to the parent topic is also automatically generated at the end of the child topic. The short description, however, is not listed under the link. But, you can hover your cursor over the link and the short description is displayed. (This is also the case for Related Information links.)

•  Search engine results for online documents
  
  Short descriptions appear in search engine results. So, well written short descriptions lets the searcher know that the information required is in your document. If you put key terms in your short description, your ranking in search results will be improved. That is, your document will show up in the search results before other documents.

 

Summary

Effective short descriptions are an opportunity to help users easily find the correct information for which they are looking. Satisfied documentation users lead to satisfied product users. Satisfied product users lead to good product reviews. Good product reviews lead to good sales numbers.

Best Practice--The conref file

As I mentioned in an earlier post, the conref attribute is one of the most useful tools DITA has for reuse. (See Reuse--The conref attribute.) Conrefs allow you to refer to an element and use its content in place of the current element. 

Usually, you will use the conref attribute to reuse lists, steps, notes, and product names. You can even use conrefs on whole paragraphs and tables. As most writers are painfully aware, product names, GUI labels, and object names are constantly changing throughout the development process. And, therefore, they make excellent candidates for conrefs. 

As a best practice, set up a file that is designated just for that purpose. That is, put your entire source for names in a conref file. (You can use the generic Topic template.) When you go to insert a conref in your target file, you won’t have to hunt for the source. You will know exactly where to find it. 

Now, each time developers change a name, you simply make the change in one, easy-to-find file.