1. DITA Short Description Guidelines
Michelle Carey and Shannon Rouiller

2. What these guidelines cover
How short descriptions work
Why care about writing good short descriptions
Topic types we’ll cover
Concept, task, and reference
API reference
Sample
Tutorial
What’s new
Troubleshooting container
Message container

3. What is the DITA short description?
A short description is content that appears in the <shortdesc> DITA element.
The <shortdesc> element goes directly after the topic title element.
Short descriptions serve the following purposes:
They are the first paragraph in a topic unless you also use the <abstract> element.
They appear in popup link text when you hover over a link to that topic.
They appear after child link titles.
They appear in Internet search results.

4. First paragraph of a topic

5. Link text in hover help
If you hover your cursor over “Crawler plug-ins,” you see the popup text.

6. Short description text in child links

7. Internet search results from Google

8. Pre-Quiz Are any of these short descriptions good ones:
Topic title: File formats for the Export, Import, and Load utilities
Shortdesc: The following table describes each of the five file formats that is supported by the Export, Import, and Load utilities. Descriptions of the five file formats are provided:
Topic title: Privileges and authorities for the Import utility
Shortdesc: Privileges enable users to create or access resources. Authority levels provide a method of grouping privileges and higher-level maintenance and utility operations. Together, these act to control access to the database objects. Users can access only those objects that they have appropriate authorization for, that is, the required privilege or authority.
Topic title: autorestart - Auto restart enable configuration parameter
Shortdesc: <blank>.
Topic title: Importing data
Shortdesc: Read this topic to learn how to import data.
Answer: No. And by the end of this presentation, you should understand why.

9. What makes a short description ineffective?
Simply repeats the title
What’s the point of simply repeating the title?
Is not a full sentence
All short descriptions must be full sentences to aid translation. You might decide to make exceptions to this rule for specific topic types such as API reference topics.
Says too much
Short descriptions should be short. Give only enough information so that the user knows whether to read on. Also, if possible, give just enough information so that advanced users can get what they need from the short description and not need to read more.

10. What makes a short description ineffective?
Includes a list lead-in
Let’s say you have a list of prerequisites and the lead-in is in the shortdesc element, but the list is in a refbody element. To reuse the list, you must use both the shortdesc and the refbody (or paragraph inside the refbody.) It’s no longer so easy to reuse the list.
Notice how the list lead-in will appear in hover text for a link, in search results, or in a child topic. The list lead-in won’t make sense in a shortdesc because the list items won’t be visible in these cases.

11. What makes a short description ineffective?
Is self-referential:
Don’t refer to the topic in the short description.
Example: “This topic will describe [or discuss or cover] things and stuff.” Short descriptions should not be self-referential.

12. Writing guidelines
Short descriptions should contain 50 words or fewer in one or two sentences. Try to keep short descriptions to about 25 words. Long short descriptions (oxymoron?) must be rare.
All topics must have short descriptions. If you think you cannot create effective short descriptions, talk to your editor, architect, or team lead first.
Remember that if some topics have short descriptions and some don’t, your information set, or library, will be inconsistent. Imagine what a set of child links will look like with only some topics with short descriptions.

13. Specific guidelines for different topic types
In addition to the general guidelines we just over covered, we’ll show you guidelines for writing short descriptions for specific topic types.
Your DTD might not have all these topic types available.

14. Concept short descriptions
Concept short descriptions provide:
Answers to what is this? or why should I care about this?
Definitions
Ensure that concept short descriptions don’t “build up” to a point. Get to the point quickly. Put your main point, or thesis statement, in the short description.

15. Concept short description examples
Ineffective
“Crawlers”
This topic is about crawlers, which are programs that search for information.
Effective
Crawlers are programs that search for information on the Web, in databases, or in other data sources. The information that the crawlers gather is added to the search engine index.

16. Concept short description examples
Ineffective
“Enterprise bean deployment tool”
Generates deployment code.
Effective
The enterprise bean deployment tool helps you create deployment code for your enterprise beans before you run them on a test server or a production server.

17. Task short descriptions
Task short descriptions define:
What the topic helps you accomplish
The benefits of the task
The purpose of the task
Situations when the task is useful or necessary

18. Task short description examples
Ineffective
“Changing data types”
You can use the ALTER NAME statement to change the data type of a column.
Effective
You can change the data type of a column so that your data types are consistent across tables. Use the ALTER NAME statement to change the data type of a column.

19. Task short description examples
Ineffective
“Applying hit counts to process breakpoints (BPEL)”
Shows how to apply hit counts to process breakpoints (BPEL).
Effective
In the Breakpoints view, you can apply hit counts so that breakpoints can be processed. When you specify a hit count for a breakpoint and that hit count is reached, the breakpoint stops the thread.

20. Reference topic short descriptions
Reference topic short descriptions show:
What the reference object does
How the referenced item works
What the referenced item is used for

21. Reference short description examples
Ineffective
“COUNT command”
KittyPro on AIX provides a COUNT command.
Effective
The COUNT command displays the current number of rows in the table. The rows are counted by the SQL SELECT COUNT(*) function.

22. Reference short description examples
Ineffective
“CatStatsCache log file”
This log file describes the cat statistics cache.
Effective
The CatStatsCache log file describes the cache that holds the cat statistics. You can use the information that is in this log file to find problems with servers that are in other tiers.

23. Sample topic short descriptions
Briefly explain what the sample shows or provides.
Optional: Mention the sample, but do not mention the topic.
You can use the word “sample" in the short description, but do not use the phrase “sample topic" or “sample task."

24. Sample topic short description examples
Ineffective
“Sample module: Portlet for opening pages”
This topic contains a sample module for opening pages.
Effective
This sample module is a standard portlet that you can adapt to open pages in the KittyPro administrative console. This sample requires KittyPro Version 6.1.

25. Tutorial short descriptions
Briefly mention what the user will learn by taking the tutorial.
For example: "Learn how to do X by using Product Y." The short description can also provide brief information about what to expect from the tutorial or lesson.

26. Tutorial short description examples
Ineffective
“Data replication tutorial”
You can use the high-speed data replication technology to replicate data over message queues. To do this, you must set up and run the KittyPro server and the DoggiePro message service.
Effective
In this tutorial, you will use the high-speed data replication technology to replicate data over message queues. You will set up and run the KittyPro server and the DoggiePro message service.

27. What’s new topic short descriptions
A What's new topic describes the latest updates to a product for a specific release. In the short description, you can mention one or more of the following items:
Two or three of the most important new features
Where users can find information about other components in the product
What component the new features pertain to

28. What’s new topic short description examples
Ineffective
“What's new for DogData V9.1: Highlights of Version 9.1 summary”
DogData Version 9.1 for Linux, UNIX, and Windows delivers new features that address the needs of your business, whether you want to integrate business data from across your organization, reduce costs, or provide a secure information management system for your company's valuable information assets.
Effective
DogData Version 9.1 for Linux, UNIX, and Windows delivers new features, such as information as a service, improved large database management, and improved database security and resiliency.

29. What’s new topic short description examples
Ineffective
“What's new in Kitty Manager for z/OS?”
Version 8.3 continues to deliver a real return on investment to customers. Version 8.3 focuses on five areas: integration, open systems, autonomic systems, resiliency, and ease of use. These highlights, and other enhancements to the Version 8.3 product, are summarized below:
Effective
Version 8.3 enhancements focus on five areas: integration, open systems, autonomic systems, resiliency, and ease of use.

30. API reference short descriptions (for generic, nonspecialized reference topics)
For API reference topics, the short description might say:
What the API does
What the API is
What the API is used for
What the API returns
Whether the API is deprecated
These API topic guidelines do not apply to conceptual or task-based programming topics. Programming topics should use task or concept topic types and follow the short description guidelines for those topics.

31. API reference short description examples
Ineffective
“getCode method”
<blank>
Effective
Returns the status code from the data listener.
You should include an effective short description even for very short API reference topics.
You can use fragments in the short description. However, ensure that all topics of this type follow a consistent format: use all fragments or use all full sentences.

32. API reference short description examples
Ineffective
“DogDatastoreDefFed class”
Accesses federated data store information.
Effective
Defines methods to access federated data store information and to create and delete federated entities and create and delete search templates. You can also use other methods to access search templates and server information.

33. Troubleshooting container topic short descriptions
A troubleshooting container topic should introduce the collection of troubleshooting topics.
Container topics serve as navigation aids. Our policy is that all container topics have a title and at least a short description.
Provide enough information so that users understand the type of troubleshooting topics that will follow the container topic.

34. Example of a troubleshooting container topic

35. Troubleshooting container topic short description examples
Ineffective
“Troubleshooting installation problems for enterprise search”
The troubleshooting topics include the following:
Effective
Installation problems might include unsuccessful installation of prerequisite software, services or processes not running, and so on.

36. Troubleshooting container topic short description examples
Ineffective
“Troubleshooting the resource manager”
This section provides troubleshooting information to help you solve some common resource manager problems.
Effective
Resource manager failures can include problems with the database, secure sockets layer (SSL), and other component connections of the kitty management system.

37. Message container topic short descriptions
You can mention which component of the product the container topic describes.
For example, a message container for a search engine product might contain messages for the index or for the crawlers.
For a database product, the container might include messages for security or for access privileges.

38. Message container topic short descriptions
Ineffective
“Search API messages (FFQQ)”
These messages describe problems with the search APIs.
Effective
Search API messages are returned when you submit requests by using the enterprise search SIAPI implementation. Operations that use the API include starting and stopping search for a collection and submitting search requests.

39. Message container topic short descriptions
Ineffective
“API messages: DGL DGL1620”
You might receive any of the following messages from the APIs. To search for the message in the information center, enter the full message number, including the prefix.
Effective
API messages describe problems with the Java and C++ connectors.

40. Quiz time What’s wrong with these short descriptions:
Topic title: Starting the system administration client on AIX
Shortdesc: You can start the system administration client on AIX.
Topic title: Search collections
Shortdesc: A search collection is a set of data sources that users can search with a single query. You can build new collections or continue to update existing collections. A search collection can contain data from the following sources:
Topic title: autorestart - Auto restart enable configuration parameter
Shortdesc: Specifies whether the database manager can automatically call the restart database utility.
Topic title: User Preferences: Mail window
Shortdesc: From here, set your mail window preferences.

41. Quiz answers Starting the system administration client on AIX
You can start the system administration client so that you can manage your deployment server. Use the cmadmin.sh command to start the server.
Search collections
A search collection is a set of data sources that users can search with a single query. A search collection can contain data from Web sites, file systems, and databases.
3. autorestart - Auto restart configuration parameter
This parameter determines whether the database manager can automatically run the restart database utility when an application connects to a database.
4. User Preferences: Mail window
Use this window to select a default address book, to change how you save sent mail, or to specify how you forward and receive mail automatically.
Rewrites
[not enough info to be useful] You can start the system administration client so that you can manage your deployment server. Use the cmadmin.sh command to start the server.
[uses a list lead-in] A search collection is a set of data sources that users can search with a single query. A search collection can contain data from Web sites, file systems, and databases. You can build new collections or continue to update existing collections.
[it’s a fragment; not enough info] This parameter determines whether the database manager can, in the event of an abnormal termination of the database, automatically call the restart database utility when an application connects to a database.
[“from here” makes little sense, esp if this topic were to be reused; the rest of the info is too obvious] Use this window to select a default address book, to change how you save sent mail, to specify how you forward and receive mail automatically, or specify how to refresh your Inbox.

42. Now wasn’t that fun?!