Home
Language and punctuation
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.
Transitional information in semantic blocks
Headings, stem sentences and transitional text phrases should not be used as a way of introducing semantic text blocks such as pre-requisites. The publishing process is capable of systematically adding the necessary transitional information, leading to consistency and simplicity.

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.
  - Transitional information in semantic blocks
    Headings, stem sentences and transitional text phrases should not be used as a way of introducing semantic text blocks such as pre-requisites. The publishing process is capable of systematically adding the necessary transitional information, leading to consistency and simplicity.
  - Stem sentences in task topics
    Stem sentences cannot be used to introduce steps in a task topic. The topic title provides sufficient context for the user to understand the purpose of the procedure.
- 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.
- 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.

Transitional information in semantic blocks

Headings, stem sentences and transitional text phrases should not be used as a way of introducing semantic text blocks such as pre-requisites. The publishing process is capable of systematically adding the necessary transitional information, leading to consistency and simplicity.

Transitional text in elements such as pre-requisites (prereq), context statements (context), results (result), and post-requisites (postreq) should be omitted.

There are a number of ways in which transitional text is incorrectly included in semantic blocks, such as in the following examples:

In this topic... (within shortdesc)
The system must meet the following conditions before starting the procedure... (within context)
Before entering the PIN you must complete some important checks... (within prereq)
After completing the procedure you will find... (within postreq)
In this procedure, the steps for... (within context)

In DITA, alternative devices and a minimalist approach are used in place of transitional text. These devices include a publishing process that can systematically apply labels to parts of the output. For example, the words Before you begin and a graphical icon can be rendered in the output immediately before every pre-requisite prereq element text. Such systematic and consistent labelling allows semantic elements to be easily identified by the reader.

If your publishing process treats semantic elements such as postreq in the same way as normal paragraph (p) elements, you should change your publishing process to generate transitional information rather than change your writing approach to introduce redundant transitional information in your content.

Do not include labels, such as Note, within the text of admonishment elements. The appropriate label or formatting will be applied when the paragraph is rendered during publishing.