What Makes a Topic a Good DITA Topic?
A DITA topic is effective when it meets specific criteria, this post makes the criteria clear
A DITA topic is a small, self-contained unit of information designed to answer one specific user need. Not a chapter. Not a page. Not a long narrative. One purpose. One job.
If you remember nothing else, remember this: DITA topics exist to do one thing for one user intent — clearly, consistently, and reuse-ready. 🧐
That single idea explains why DITA works so well at scale and why it behaves differently from traditional document-centric authoring.
See also: What is the Darwin Information Typing Architecture (DITA)?
What Makes a Topic a Good Topic?
A DITA topic is effective when it meets these criteria:
Single intent — It answers one question or supports one task
Self-contained — It makes sense without relying on surrounding prose
Context-aware — Metadata defines product, version, audience, and conditions of use
Reusable by design — It can appear in multiple documents without rewriting
If a piece of content reads awkward when reused, it probably wasn’t written as a true topic.
Why DITA Topics Exist
Before DITA, most technical documentation followed a document (book) model:
Long manuals
Linear chapters
Content written once, reused by copy-paste
Updates scattered across multiple files
That model breaks down when you need to:
Reuse content across products and versions
Publish to multiple outputs (PDF, web, help systems, chatbots)
Keep information accurate over time
Support automation, search, and AI
DITA flips the model. Instead of starting with a document, you start with topics.
The Three Core Types of DITA Topics
Most DITA implementations rely on three foundational topic types. Each enforces intent.
1. Concept Topics — “What is this?”
Concept topics explain ideas, principles, or background information.
Examples:
What a feature does
Why a setting exists
How a system behaves
They help users understand before they act.
2. Task Topics — “How do I do this?”
Task topics walk users through steps to complete a goal.
Characteristics:
Clear goal
Prerequisites
Ordered steps
Expected results
They answer action-oriented questions and work especially well for procedural content and automation.
3. Reference Topics — “What are the details?”
Reference topics provide structured facts.
Examples:
Parameters
Commands
Error codes
Field definitions
They prioritize accuracy, consistency, and scannability over narrative flow. 🤠