The blurred line between content and form

Text that labels the content that follows should be applied in the publishing process, and not included in the content itself.

The difference between content and form is sometimes surprisingly difficult to identify.

For example, in the following sample, the word "Note:" looks like part of the content, but on deeper reflection, it turns out to be part of the presentational form.

Screen capture showing difference showing one rendition of a Note

This becomes more obvious when you look at alternative ways of presenting the same information, such as the following:
Screen capture showing difference showing a rendition of a Note with an icon


Screen capture showing difference showing a rendition of a Note with borders

The mark-up of that element in DITA must always follow the pattern:
<note>Before having...</note>
and never:
<note>Note: Before having...</note>

Embedding the label for an element in its text will limit the ways in which the element can be presented.

Ensuring that form is not mixed with content can be quite challenging when publishing tools don't make a sufficient distinction between text with a specific purpose and more general text. For example, when task topics are published through the default DITA Open Toolkit, no special formatting or labelling is applied to pre-requisite (prereq) elements. Avoid the temptation to add form to the content, and instead work to modify the publishing templates, stylesheets and processes so that the required formatting is applied during processing.

Ensuring that labels are applied in the publishing process rather than in the content will also simplify localisation, as there is less text to translate.