information-typing-conceptsUnderstand the foundational principles of topic-based structured authoring and why tasks, concepts, and references are separated.
Information typing is the practice of categorizing documentation content by its communicative purpose rather than by document chapter or medium. Rooted in Robert Horn’s Information Mapping methodology and formalized in the OASIS DITA standard, information typing establishes that readers approach technical documentation with distinct cognitive needs.
The three core information archetypes
Instead of mixing narrative descriptions, step-by-step instructions, and technical specifications into continuous prose, structured authoring isolates each purpose into a distinct topic type:
- Tasks (Procedural): Answer How do I? with concrete, sequential commands leading to a verifiable outcome.
- Concepts (Explanatory): Answer What is it? and Why does it work this way? to help readers build accurate mental models.
- References (Factual): Answer What are the parameters? by presenting structured, lookup-oriented data such as tables and syntax.
Benefits of strict semantic typing
When authors adhere to clear structural contracts, documentation quality improves across multiple dimensions:
Reader efficiency and cognitive load
Readers performing maintenance do not want to wade through theoretical physics; conversely, engineers designing system architectures need conceptual clarity rather than a list of clicks. Isolating types lets readers locate exactly what they need without distraction.
Content reusability and modularity
Self-contained topics can be assembled into multiple publication formats (web portals, PDF manuals, contextual help) without duplicating or fragmenting source files.
Automated validation and consistency
Schemas enforce that tasks always have actionable steps, concepts explain background principles, and reference pages contain tabular specifications.
Implementing DITA principles in YAML without XML
Traditional DITA relies on XML schemas (DTDs, XSDs) and the DITA Open Toolkit (DITA-OT), which introduce considerable tooling overhead. By mapping DITA’s core semantics (cmd, info, substeps, stepresult, prereq, context) into clean YAML structures:
- Authors edit human-readable files that version-control cleanly with standard Git diffs.
- Modern static site generators like Astro render lightweight, accessible HTML without complex XSLT pipelines.
- Schema validators (such as Zod) enforce structural validity and cross-topic referential integrity at build time.
Application example
Consider our lawnmower maintenance documentation: the task replace-lawnmower-blade gives direct mechanical instructions, while lawnmower-blade-reference tabulates torque thresholds and dimensions, and this concept explains why keeping these two topics separate prevents dangerous confusion.