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.

Tools for reuse--The conref attribute

The conref attribute (conref stands for content reference) allows you to reuse text at an element level.

Suppose you want to reuse the text of a warning. You would assign an element ID to the note tag containing the warning text in the original file. In a second file, you would reference that warning  by using the conref attribute on a note tag.

 For example, the original file is named topic1.dita with a topic ID of 111. The note tag reads:

 <note id="damage" type="warning"> You can cause serious damage.</note>

Notice that the element ID on the note tag is damage. 

Here’s the syntax you would use for the conref attribute:

filename.xml#topicid/elementid

The note tag in the second file would read:

 <note conref="topic.dita#111/damage"/> 
 
The result would be a duplicate of the original warning.

In my next posting, I will discuss a best practice for conrefs.

Single-sourcing and reuse

A big benefit of DITA is single-sourcing.

If you publish to multiple formats (web, online help, print, and so on), you can use the same set of DITA files for each piece of content. And that means that one set of files for multiple formats can be stored in one repository. You don't have to worry about making the same updates in multiple file sets. Single-sourcing  strengthens the way you create, develop and maintain content.

Single-sourcing also allows for another key feature of DITA--reuse. With DITA, you can reuse documentation that was created for one document in another document. For example, you could use a topic in training courseware, in a user guide, and in marketing information.

 You can reuse a whole topic or part of a topic.

To reuse a topic, you would simply include the same topicref in a new ditamap. To reuse a part of a topic, you would assign an ID to the portion you want to reuse, and then use a conref attribute in the new topic to incorporate that portion.

This allows for consistent use of terminology, instructions, and concepts. And what happens when you have consistent information? Your customer gains confidence in your documentation and your product.

Before you begin

One of the most common mistakes organizations make when converting to DITA is to not properly train their writers. I’m not talking about DITA training. The training that is missed is the reason for DITA—that is, topic-based authoring. Writers that are well-trained in topic-based authoring will appreciate the benefits of DITA.

Topic-based documentation is tailor-made for users who don’t have a lot of time to read. Topic-based documentation gets to the point. Each topic answers one question: 

"How do I ..." 

"What is ...?" 

"What went wrong?"  

Topics should only be a few paragraphs long and stick to one subject. So, not only are topics easier to read, they should be easier to review. Subject Matter Experts who are reviewing the documentation will appreciate being able to quickly find and review information. And what tech writer wouldn't appreciate a cooperative (or dare I say, enthusiastic) reviewer?

One of the best examples I’ve seen regarding topic-based authoring is the example given in the article Topography, Muffins, and Chunking. Check it out and let me know if you agree.

Note: Thanks to Michael McGrail for helping me get started with this blog. For tips on increasing your productivity, check out his blog The Productivity Source.