DITA Short Description Guidelines

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 well cover
• Concept, task, and reference
• API reference
• Sample
• Tutorial
• Whats new
• Troubleshooting container
• Message container

3
What is the DITA short description?

• A short description is content that appears in
  the ltshortdescgt DITA element.
• The ltshortdescgt 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 ltabstractgt 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 ltblankgt.
• Topic title Importing data
• Shortdesc Read this topic to learn how to import
  data.

9
What makes a short description ineffective?

• Simply repeats the title
• Whats 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
• Lets 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.) Its 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 wont make sense in a
  shortdesc because the list items wont be visible
  in these cases.

11
What makes a short description ineffective?

• Is self-referential
• Dont 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 dont, 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, well 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 dont
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 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
• 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 examples

• Ineffective
• 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 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
• 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 examples

• Ineffective
• 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 examples

• Ineffective
• 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 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
• 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
Whats 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
Whats 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
Whats 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
• 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
• ltblankgt
• 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 examples

• Ineffective
• 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
examples

• Ineffective
• 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 descriptions

• Ineffective
• 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
Whats 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.

42
Now wasnt that fun?!