1 / 42

DITA Short Description Guidelines

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

micheal
Télécharger la présentation

DITA Short Description Guidelines

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  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.

  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 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-speeddata replication technology to replicate data over message queues. You will set up and run theKittyPro 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 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” <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 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 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.

  42. Now wasn’t that fun?!

More Related