Home
Language and punctuation
Titles and headings
Titles are used in a number of mark-up structures in DITA. Titles are a mix of content and metadata. The mark-up in titles should be kept as simple as possible, and workarounds to achieve specific formatting outcomes should not be used.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
Syntax and mark-up
Language and punctuation
- Avoiding writing for output
  Do not include formatting information in your DITA content topics.
- Stem sentences, glue text, and other transitional information
  Transitional information, such as stem sentences, is largely redundant in DITA's minimalist, topic-based, semantic mark-up architecture. The role of transitional information in contextualising the content has been eliminated through the use of smaller chunk sizes, meaningful titles, information typing, structure, and demarcation labels automatically-generated in the output.
- Punctuation in lists
  Ordered and unordered list items should have no terminating punctuation marks, such as commas, semicolons, and full stops, except when all items in a list are complete sentences. This approach maximises re-usability.
- Titles and headings
  Titles are used in a number of mark-up structures in DITA. Titles are a mix of content and metadata. The mark-up in titles should be kept as simple as possible, and workarounds to achieve specific formatting outcomes should not be used.
  - Case in titles
    Sentence case should be used for topic, section, figure, table and other titles.
  - Line breaks in titles
    There is no line break element or equivalent in DITA.
  - Where topic titles are used
    Topic titles are used to form the heading in the output deliverable document, as well as for other constructs such as link text and metadata values.
  - Crafting meaningful topic titles
    Writing accurate, concise and consistent topic titles is an important challenge for DITA authors. Guidelines for crafting title text make this task a little easier.
  - Conditional titles
    A title element in DITA does not have the normal metadata attributes used for conditional publishing. However, it is possible to carefully use conditions on elements nested within a title element.
- Crafting paragraphs
  A paragraph should contain one unit of thought or action, or main point, and should be typically three to eight sentences in length. All of the sentences in a paragraph should relate to its main point.
- Different languages
  The xml:lang attribute stores the human language of the content, and can be applied to any DITA element.
- Quotation marks
  Quotation marks should not be included in DITA content. The marks should be added, if required, during the publishing process.
Graphics and figures
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

Titles and headings

Titles are used in a number of mark-up structures in DITA. Titles are a mix of content and metadata. The mark-up in titles should be kept as simple as possible, and workarounds to achieve specific formatting outcomes should not be used.

A title is not the same as a heading. A title is usually considered part of the content (and is typically rendered in the output as a heading), but it also has a role as a metadata container. For example, the title might be used as the basis for link text, outside the context of its topic. In that context, mark-up such as a footnote (fn) or cross-reference (xref) wouldn't make any sense.

A number of mark-up structures in DITA have titles, including:

map
topic
table
data
link list
syntax diagram
figure
section
example

Avoid using phrase-level mark-up in titles, particularly when the motivation is to achieve a presentational outcome. For example, do not use footnote (fn) elements in titles, as the presentational outcome when a title is displayed in a pop-up window is likely to be unpredictable.

If a title element does not permit a particular type of phrase-level element, do not devise workarounds to force such elements in place.

For example, title does not permit the cite element, but does permit the general phrase (ph) element. That phrase element can itself contain cite. So while the code <title>Such is Life <ph><cite>Ned Kelly</cite></ph></title> is technically correct, it nonetheless constitutes a workaround, and should not be used.