Are there conventions for specifying element mappings in DITA specialization documentation?

Conventions for Specifying Element Mappings in DITA Specialization Documentation: To maintain consistency and clarity in DITA specialization documentation, it’s important to follow conventions when specifying element mappings. These conventions ensure that content creators can easily understand and work with the mapping relationships. Common conventions include:

  • Mapping Format: Use a clear and consistent format to represent element mappings. Typically, this involves specifying the source DITA element and its corresponding element(s) in the output format(s).
  • Structured Tables: Present element mappings in structured tables or lists. This helps organize the information and makes it easier to reference.
  • Annotations: Use annotations, comments, or labels to provide additional context or explanations for specific mappings. Annotations help content creators understand the purpose of each mapping.
  • Symbolic Notations: Consider using symbolic notations or icons to represent different types of mappings, such as one-to-one mappings, conditional mappings, or transformations.

By adhering to these conventions, DITA specialization documentation becomes more user-friendly and facilitates the effective use of element mappings in different output scenarios.

Example:

In a DITA specialization documentation, a structured table is used to specify element mappings. The table format provides clarity and concise information about how each source DITA element maps to the target elements in the output formats.


<!-- Mapping Table -->
<table>
  <tr>
    <th>Source DITA Element</th>
    <th>HTML Output Element</th>
    <th>PDF Output Element</th>
  </tr>
  <tr>
    <td>concept</td>
    <td><div class="concept"></td>
    <td><section class="pdf-concept"></td>
  </tr>
  <tr>
    <td>task</td>
    <td><div class="task"></td>
    <td><section class="pdf-task"></td>
  </tr>
  <!-- Additional mapping rows -->
</table>