<element-name> 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 <!-- ... --> . -- Best, Kris