Reference Guidelines

• Naming standard: r_product_name.dita.

• Do not use paragraphs in reference topics, except for the short description.

• Describe one type of reference material per topic.

• Organize reference information logically or tabular.

• Format reference information consistently.

• Oxygen XML recommends that we avoid the use of sections where possible. See Oxygen's article, "Avoiding chunk structure in topics".

Structure

<title>

Our CSS handles the formatting of all titles.

Topic or section title. *Use noun-based title for reference topics. Although you can't always distinguish concept titles from reference titles just by looking at the grammatical structure of the title, at least distinguish reference titles from task titles by using a noun phrase in the reference topic title. Example: DITA XML elements, Database monitoring commands, Required software for the ProStar Editor.

<shortdesc>

Introduces the reference topic. *Required. Describe what the referenced item does, is used for, or its benefits.

<refbody>

Contains the body of the topic.

<section>

Optional. Organizes content in a topic into sections. Avoid where possible.

<table>

Organize content in a table with a title. Do not set columns width.

<simpletable>

A table that doesn't require a title. Do not set columns width.

<dl>

Contains a list of terms or phrases and their definitions.

<dt>

Term (bold). The Definition Description <dd> should be slightly indented and in plain text. There should be spacing between the description and the next term.

<dd>

The definition or description. (slightly indented) Make sure to add a paragraph <p> before entering text for the <dd>.

<example>

Contains an example.

<refsyn>

The <refsyn> element is a special section inside a reference topic. The section often contains syntax or signature content (for example, the calling syntax for a command-line utility or an API signature). The <refsyn> contains a brief, possibly diagrammatic description of the subject's interface or high-level structure.

<codeblock>

Use code block when the code is more than one line long, and is a block in its own right.

<codeph>

Use when the code sample occurs inline within a paragraph or other block element.

<properties>

Lists properties of a subject and their types, values and descriptions.