Creating a glossary entry

The basics for creating and reference glossary terms.

Glossary terms appear in our company-wide Glossary list. Additionally, when a term appears in a topic, a hover or pop-up can appear over the term, and clicking the term navigates to the Glossary entry. Terms can also have a "first-use" and "subsequent uses on the same page" definitions that behave the same as a simple term.

This video illustrates the steps to complete this task.

  1. Navigate to the /content/Glossary folder.
  2. Create a Glossary Entry topic.
    Use the Term label for the Title and Filename. If it is a long name or has multiple words, it is OK to use an abbreviation, such as NPS instead of Net Promoter Score.
  3. Required: Enter a Term.
    The term should begin with an uppercase letter, such as Webhook.
  4. Required: Enter a Description.

    • You may include additional paragraphs and images in the Description. The image(s) will appear in the Glossary but not in the hover bubble.

    • The portal will attempt to put all of the text in the hover bubble. Try to keep the term concise.

  5. Optional: Add a Usage description to explaining more information about the term and how to use it.
    If you are going to add a cross reference to a documentation topic, do it here. Be conscious of @audience settings in the target content, for example, use audience="private" for most Experience Cloud content.
    Restriction: Use a keyref link; do not use an href link. For information, see Cross references (<xref>).
  6. Optional: Add a Surface Form and a (GlossAlt) Acronym to be used for Abbreviated Form (which is first-use and subsequent appearances on the same page.
    When using an <Abbreviated Form> element, the first occurrence on the page is rendered using the Surface Form value, and all subsequent occurrences use to Acronym value. It is good practice to include the Acronym in the Surface for entry. For example, when the Acronym is NPS, the Surface Form is Net Promoter Score (NPS).

    Note, if you use <Abbreviated Form> and there is no Surface Form or Acronym, the portal shows the Term value.

  7. Assign an ID to the topic: to the GlossEntry element.
    The ID begins with "glossary-" followed by the term. It is OK to abbreviate long names.
  8. Close (and save) the Glossary Entry.
  9. Open the _Glossary (ditamap).
  10. Add the new Glossary Entry to the map.
  11. Required: Add a key to the map entry. This is the key all <term> and <abbreviated-form> elements reference.
    The key begins with "glossary-" followed by the term. It is OK to abbreviate long names. For consistency, use the same values for the map key and for the entry ID.
  12. Close (and save) the map.
    You can now reference the key in topics.
    Tip: When editing a topic, use the _Glossary map as the Content for the topic. Then you can select the ID from the list of glossary keys.
  13. When ready, merge the map and the glossary entry into the Company-production branch.
The glossary entry will now appear in the Glossary topic and can be referenced by other topics, including other Glossary entries.
Note: SEE MIKE for tips on referencing "For more information, see <product topic>. He still needs to write this up. :)