joe_storbeck's blog

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.

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.

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. 

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. 


Tools for reuse--The conref attribute

The conref attribute (conref stands for content reference) allows you to reuse text at anelement 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:

Notice that the element ID on the note tag is damage

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. 

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.


Subscribe to RSS - joe_storbeck's blog