Organising elements within re-use topics

You should use logical, identifiable id attributes. Short phrase-level elements intended for re-use can be organised into tables for ease of maintenance.

Easy-to-identify id attributes should be used for re-use elements. In choosing names, you should prefix the id values to indicate the purpose of the element, such as:
var_
for short re-use phrases and variables
term_
for terms and definitions
step_
for task steps
warning_
for warning notes
fig_
for figures

To provide a reference for how re-use elements are meant to be used, you may choose to organise re-use phrases (or variables) into tables, where a description of the element's intended use can be documented alongside the re-use content.


Screen capture of DITA editor showing conref variables organised into a table

Conref source file with re-use elements organised with a table