Title Guidelines

• Use title case
• Use nouns or noun phrases
• Include the referenced subject, interface, etc.

Examples: “DITA Open Toolkit Errors”, “Element Properties”

Style Guidelines

• Organize content into scannable structures (such as tables, bullet lists, code blocks)
• Provide only reference information, not conceptual or procedural information

Considerations

Ask yourself the following questions when creating reference topics:

• Is there any reference information to support concept or task topics?
• How can I organize this reference content so it can be easily scanned?

Structure

reference topics can contain the following elements:

• reference element
  1. title element
  2. abstract element
     • short description element
  3. prolog element
  4. reference body element
     • section element
     • table element
     • example element

Elements

title element

Entitles a topic, a section, or a container element.

abstract element

Provides introductory content that would be unfit for a short description element.

short description element

Illustrates the topic purpose in two or three sentences (no more than 50 words). short description elements can provide content for link previews and search engines.

prolog element

Contains topic metadata. Can contain multiple resource ID elements that you can use to implement context-sensitive help into applications.

reference body element

The main element of a reference topic.

section element

Contains relevant content.

table element

Contains scannable reference material.

example element

Illustrates or supports a topic by providing relevant examples.

Reference Topic Example