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

1. 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:

2. 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.

3. Topic title: autorestart - Auto restart enable configuration parameter Shortdesc: <blank>.

4. Topic title: Importing data Shortdesc: Read this topic to learn how to import data.

Are any of these short descriptions good ones:

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” 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

“Enterprise bean deployment tool”

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 accomplishThe benefits of the taskThe purpose of the taskSituations 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

“Changing data types”

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 examplesIneffective

“Applying hit counts to process breakpoints (BPEL)”

Shows how to apply hit counts to process breakpoints (BPEL).

Effective

“Applying hit counts to process breakpoints (BPEL)”

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 doesHow the referenced item worksWhat the referenced item is used for

21

Reference short description examples

Ineffective

“COUNT command”

KittyPro on AIX provides a COUNT command.

Effective

“COUNT command”

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 examplesIneffective

“CatStatsCache log file”

This log file describes the cat statistics cache.

Effective

“CatStatsCache log file”

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 examplesIneffective

“Sample module: Portlet for opening pages” This topic contains a sample module for opening

pages.

Effective

“Sample module: Portlet for opening pages”

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 examplesIneffective“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“Data replication tutorial”

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

“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,

such as information as a service, improved large database management, and improved database security and resiliency.

29

What’s new topic short description examplesIneffective

“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

“What's new in Kitty Manager for z/OS?”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

“getCode method”

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 examplesIneffective

“DogDatastoreDefFed class”

Accesses federated data store information.

Effective

“DogDatastoreDefFed class”

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 examplesIneffective

“Troubleshooting installation problems for enterprise search”

The troubleshooting topics include the following:

Effective

“Troubleshooting installation problems for enterprise search”

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

“Troubleshooting the resource manager”

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 descriptionsIneffective“Search API messages (FFQQ)”

These messages describe problems with the search APIs.

Effective“Search API messages (FFQQ)”

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: DGL0300 - 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: DGL0300 - DGL1620”

API messages describe problems with the Java and C++ connectors.

40

Quiz time

1. Topic title: Starting the system administration client on AIX Shortdesc: You can start the system administration client on AIX.

2. 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:

3. Topic title: autorestart - Auto restart enable configuration parameter Shortdesc: Specifies whether the database manager can

automatically call the restart database utility.

4. Topic title: User Preferences: Mail window Shortdesc: From here, set your mail window preferences.

What’s wrong with these short descriptions:

41

Quiz answers1. 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.

2. 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.

42

Now wasn’t that fun?!