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.