Transcript Short Descriptions

DITA Short Description
Guidelines
Michelle Carey and
Shannon Rouiller
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
2
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.
3
First paragraph of a topic
4
Link text in hover help
If you hover your cursor over “Crawler plug-ins,” you see the popup text.
5
Short description text in child links
6
Internet search results from Google
7
Pre-Quiz
Are any of these short descriptions good ones:
1.
2.
3.
4.
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 higherlevel 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.
8
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.
9
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.
10
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 selfreferential.
11
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.
12
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.
13
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.
14
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.
15
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.
16
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
17
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.
18
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.
19
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
20
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.
21
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.
22
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."

23
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.
24
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.
25
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.
26
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
27
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.
28
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
“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.
29
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.
30
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.
31
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.
32
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.
33
Example of a troubleshooting
container topic
34
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.
35
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.
36
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.
37
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.
38
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.
39
Quiz time
What’s wrong with these short descriptions:
1.
2.
3.
4.
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.
40
Quiz answers
1.
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.
41
Now wasn’t that fun?!
42