Reference Topics

Reference topics provide structured, factual information that complements and supports both task and concept topics.

Reference content should be concise, easy to scan, and non-narrative. Examples include configuration tables, field definitions, API specifications, and system requirements. Reference topics consolidate information that users need to look up for quick reference.

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.

Best Practices for Writing

Prioritize ease of lookup over narrative flow.
Use consistent formatting for similar information types.
Include searchable keywords and synonyms.
Organize information logically (for example, by importance, by workflow, or alphabetically).
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>