Short Descriptions

Short descriptions provide an overview of a topic and answer the question "What is this about?" They also play a role in search results and link navigation.

Short descriptions present the purpose or theme of the topic. In topic content they appear at the top of the page, below the title and before the first paragraph. A well-written description helps the reader identify whether the topic contains useful information. Further, search results that point to a page often use the page's short description as a preview or summary of the link. These descriptions can influence click-through rates and indirectly affect search rankings. As such, providing a good short description provides both a service to the reader, and can influence a topic's search-result relevance.

Note: Medallia documentation for Medallia Experience Cloud formerly use Short Descriptions as a "breadcrumb" map to identify the software screen a topic applied to. Some older pages retain that notation. However, such usage is discouraged in favor of making descriptive overviews instead.

Short descriptions are also used in sitemaps to provide a summary of the navigational links or "tiles".

Example of a short description in a sitemap

Guidelines for writing a short description

  • Every topic should have a short description.

  • The description is a single, concise paragraph containing one or two sentences of no more than 50 words.

  • Do not start with "This topic …", or include the text "…this topic…", etc. The description is about the content, not the structure.

  • Do not simply repeat the title.

  • Include keywords that will help the reader and search engines identify whether the topic contains useful information.

  • Avoid using the short description to lead in or build up to a topic. The short description paragraph should contain the main point of the topic.

  • For tasks, explain the purpose of the task and what users can accomplish by completing it. Try to include information that will help users understand when the task is appropriate or why the task is necessary. Avoid stating the obvious, such as "You can use XYZ to do A" as the only statement in the short description for Task A.

  • When in a sitemap, the text should be no longer than a sentence so that it fits in the navigation tile