Style guidelines for the DITA specification

Covering goals for editorial consistency in the DITA specification. Many of these are inconsistent in 1.2 and will be fixed as encountered or as time permits.

General consistency

Marking revisions

Revision values are controlled with a subject scheme map. For 1.3, the values in use are:

Phrase level markup

Code samples

Inline, partial code samples must be marked up with <codeph>. These do not need to be complete; for example, a <codeph> element may contain a sample start tag, with no end tag.

Complete code samples must be marked up with <codeblock>. They must show a useful instance of the markup in question. Markup in the code block must be valid DITA XML; an author must be able to paste it into a DITA editor. This means that elements which start must also end, and required attributes / sub-elements must be present. Use two characters for each level of indentation.

Some samples start or end with "..." characters to indicate that the sample appears inside other markup. This is acceptable, though generally unnecessary. If "..." is used in the middle of a sample, either it must be used in a context where text is valid, or it must be placed inside comment tags: <!-- ... -->

If the example uses a large amount of required markup in order to highlight a single element, the <b> element may be used to highlight that element's start and end tag.

Draft comments

Authors or editors inserting <draft-comment> elements must use the @author and @time attributes. Draft comments will be deleted when they are resolved or no longer germane.

Examples

Complex examples belong in the Architectural Specification. The Language Reference topics should include a short example that illustrates the usage of the element. If the element has processing implications, the example should elucidate them.

Examples should be contained within <example> elements. If an entire topic is used for an example, the <title> should use the following format: "Example: X".

Example paragraphs within the Architectural Specification should 1) Begin with the phrase "For example," and 2) be marked with outputclass="example".

Every <example> should set the ID attribute. In the language specification, for consistency, the first or only <example> always uses id="example". Additional examples in a language specification topic may use any valid ID.

Indexing

Index term entries must only be in the prolog. Kris and Robert are planning to meet about developing a long-term plan for indexing; other TC members are welcome to participate.

Submaps

Submaps must have <title> elements. If the <map> element has a @navtitle attribute, remove it.

Open items for Kris and Robert to discuss

Some tables use <desc>; others do not. What is preferred?

DitaSpecStyleGuide (last edited 2015-05-08 10:09:05 by keberlein)