Decision 03: Cross-Reference Convention
Status
Accepted
Date
2026-02-18
Context
With three document types that frequently reference each other, a consistent cross-reference convention is essential. Early versions of the templates used numeric document codes in cross-references, which created several problems:
- Readers unfamiliar with the numbering scheme couldn’t tell which document was being referenced
- The numeric codes were confused with use case numbers or version numbers
- When the naming convention changed, all cross-references needed updating
Decision
Use the document type abbreviations PAD, OAD, and SDD for all cross-references within document content, accompanied by the section number and optionally the section title.
Format: PAD §3.4 Architecture Decision Records or SDD §5.1
Rules:
- Always use the abbreviation (PAD, OAD, SDD), never numeric codes
- Include the section number using the
§symbol - Include the section title alongside the number for resilience against section renumbering (recommended but not required for well-known sections)
- The document type suffix (PAD, OAD, SDD) appears in both filenames and cross-references, ensuring consistency
Rationale
- Readable: “Refer to PAD §6.2 Network Architecture” is immediately understandable without knowing the naming convention
- Stable: If section numbers change, the section title provides a fallback for locating the referenced content
- Unambiguous: PAD/OAD/SDD are distinct abbreviations that cannot be confused with each other or with numeric identifiers
- Consistent: The same convention works regardless of how many documents exist in the project
Consequences
- All templates must use this convention consistently — the “How to Use This Template” preamble in each template reinforces it
- The glossary in each template should define PAD, OAD, and SDD abbreviations
- When a section is renumbered, cross-references using section titles remain findable even if the section number is outdated