Reference Topics

Use

Reference topics are used to provide structured, factual data. They are ideal for configuration tables, field definitions, API specifications, system requirements, error codes, and feature comparison tables. They support concept or task topics by providing detailed data users might need during or after a task. Reference content should be concise, easy to scan, and non-narrative.

User Intent

"I need to find specific information quickly."

Common Tags

• <reference>: Root element.
• <title>: Topic title.
• <shortdesc>: Brief introduction.
• <refbody>: Container for detailed data.
• <section>, <table>, or <properties>: Structured content.

Design Principles

• Prioritize scannability over narrative flow.
• Use consistent formatting for similar information types.
• Include searchable keywords and synonyms.
• Organize information logically (alphabetical, by importance, by workflow).
• Provide cross-references to related concepts and tasks.

Sample XML Code

<reference id="systemreqs">
  <title>System Requirements</title>
  <shortdesc>Minimum and recommended requirements for installation.</shortdesc>
  <refbody>
    <table>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Component</entry>
            <entry>Requirement</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>Operating System</entry>
            <entry>Windows 10 or later</entry>
          </row>
          <row>
            <entry>RAM</entry>
            <entry>8 GB minimum</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </refbody>
</reference>