Presentation on theme: "DITA Short Description Guidelines"— Presentation transcript:
1 DITA Short Description Guidelines Michelle Carey and Shannon Rouiller
2 What these guidelines cover How short descriptions workWhy care about writing good short descriptionsTopic types we’ll coverConcept, task, and referenceAPI referenceSampleTutorialWhat’s newTroubleshooting containerMessage 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.
8 Pre-Quiz Are any of these short descriptions good ones: Topic title: File formats for the Export, Import, and Load utilitiesShortdesc: 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 utilityShortdesc: 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 parameterShortdesc: <blank>.Topic title: Importing dataShortdesc: 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 titleWhat’s the point of simply repeating the title?Is not a full sentenceAll 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 muchShort 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-inLet’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 guidelinesShort 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?DefinitionsEnsure 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.EffectiveCrawlers 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.EffectiveThe 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.EffectiveYou 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).EffectiveIn 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.EffectiveThe 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.EffectiveThe 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.EffectiveThis 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.EffectiveIn 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 featuresWhere users can find information about other components in the productWhat 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.EffectiveDogData 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:EffectiveVersion 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 doesWhat the API isWhat the API is used forWhat the API returnsWhether the API is deprecatedThese 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>EffectiveReturns 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.EffectiveDefines 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.
35 Troubleshooting container topic short description examples Ineffective“Troubleshooting installation problems for enterprise search”The troubleshooting topics include the following:EffectiveInstallation 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.EffectiveResource 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.EffectiveSearch 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.EffectiveAPI 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 AIXShortdesc: You can start the system administration client on AIX.Topic title: Search collectionsShortdesc: 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 parameterShortdesc: Specifies whether the database manager can automatically call the restart database utility.Topic title: User Preferences: Mail windowShortdesc: 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 collectionsA 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 parameterThis parameter determines whether the database manager can automatically run the restart database utility when an application connects to a database.4. User Preferences: Mail windowUse 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.