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 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.