shortdesc

The short description should explain what the task information helps users accomplish, the benefits of the task, or the purpose of the task. Do not simply repeat the title. Try to include information that will help users understand when the task is appropriate or why the task is necessary. Avoid stating the obvious, such as "You can use XYZ to do A" as the only statement in the short description for Task A. In some cases, add more information about why the task is beneficial.

Do not use sentence fragments. Use complete sentences. Avoid starting short descriptions with phrases such as "This topic describes . . . ." or "This topic is about . . . ."

Introduce the concept and provide a concise answer to the question "What is this?" and in some cases "Why do I care about this?" If the concept is unfamiliar, you can start with a brief definition. Avoid using the short description to lead in or build up to a topic. The short description paragraph should contain the main point of the conceptual topic. The concept short description should clearly apply to a concept. Avoid turning the concept topic into a task. Do not simply repeat the title.

Do not use sentence fragments. Use complete sentences. Avoid starting short descriptions with phrases such as "This topic describes . . . ." or "This topic is about . . . ."

Briefly describe what the reference item does, what it is, or what it is used for.

In most cases, use a complete sentence. You can use a sentence fragment only for a topic that is very short, such as an API topic and each of its subtopics. Use consistent phrasing across libraries and information centers so that your information can be seamlessly integrated with another product's information.