Guidelines for element-reference topics

The short description should follow the following patterns:

Use natural language whenever possible. This is critical for elements that are shared with LwDITA.
Be sure and describe what something is â or the primary function that it serves. For example,ÂA short description describes the purpose or main point of a topic.

Usage information

Use this section to provide additional information that is necessary for a reader to understand the element. This section focuses on information that is necessary for an author writing in DITA to understand. For example:

"TheÂ<dita>Âelement cannot be specialized. It is provided as a container that can manage any sequence of any type of topic. Topic nesting rules can be configured in the document-type shell."

Convenience elements should have paragraphs that contain the following information:

"TheÂ<linktitle>Âelement is a convenience element. It is equivalent to aÂ<titlealt>Âelement withÂ@title-roleÂset toÂlinking."

Rendering expectations

Use this section to explain any rendering expectation for the element. In general, rendering expectation are about how the content will show up "on the glass." For example:

"Processors SHOULD render the content of theÂ<shortdesc>Âelement as the initial paragraph of the topic."

Be sure to distinguish between rendering and formatting expectations; formatting expectations go in a non-normative appendix topic.

One way to distinguish between rendering and formatting is that rendering expectations are important for interoperatibility. For example, in certain cases, it is important that rendering application are consistent in choosing what content to display: theÂ<shortdesc>Âis rendered, and when anÂ<object>Âcannot be displayed theÂ<fallback>Âis rendered.

Formatting can vary without impacting the content itself, such as how indentation works forÂ<dl>Âor how aÂ<note>Âelement is styled to stand out.

Processing expectations

Use this section to explain processing expectations for the element. In general, processing expectations help enforce consistency in how conforming DITA processors work with an element. Implementors need to pay special attention to any element that has this section. For example:

"When aÂ<shortdesc>Âelement occurs in a DITA map, it overrides the short description provided in the topic for the purpose of generating map-based link previews. It does not replace theÂ<shortdesc>Âin the rendered topic itself. This means that generated map-based links to this topic will use the short description from the map for any link previews provided with the link, while the rendered topic continues to use the short description inside the topic."

Specialization hierarchy

This section will appear for any element that is specialized from another element. Use the following type of wording:

"TheÂ<linktitle>Âelement is specialized fromÂ<titlealt>. It is defined in the alternative-titles domain module."

Attributes

Attribute descriptions have been simplified from DITA 1.3. While not visible in DITAWeb or in the PDF, linked attribute groups in the OASIS-styled HTML will display hover text that lists all attributes. In most cases we have tried to eliminate wording such as "Uses the display attribute group except for X" or "Uses X and Y from the linking attribute group", in favor of simply listing the attributes (which link directly to the definition).

Example

This section should have a title of eitherÂExampleÂorÂExamples, depending on whether there are multiple examples.

(If there are multiple examples) The section should be introduced with a paragraph; use the following phrasing:

"This section contains examples of how theÂ<myElement>Âelement can be used."

Each example should be in aÂ<fig>Âelement with a title. Each code sample should be introduced with a paragraph that explains what the code sample does and its relevance; we use the following phrasing:ÂThe following code sample shows ...

The code samples should be realistic, if it all possible. The relevant elements in the code sample might be highlighted (bold) to draw the readers attention. Code samples should be indented four spaces.

If content is "snipped" from the code sample, it should be indicated withÂ.