Topic-based authoring: a practical guide

Topic-based authoring is the writing discipline that makes a component content management system actually work. The CCMS holds the components; the authoring discipline decides whether the components are actually independent enough to be reused.

This post is a practical guide. What topic-based authoring is. What DITA’s three topic types cover and what they do not. The change in writing habits the discipline asks for. The common failure modes and how to spot them in a draft.

What it is

Topic-based authoring writes content in small, self-contained units (topics) that can stand alone or assemble into longer documents. Each topic covers one subject, answers one question, or describes one procedure. The unit of work is the topic, not the document. Documents are assembled from topics on demand.

DITA’s three topic types: concept on the left, task in the middle, reference on the right. The thin connectors are content references, the reuse mechanism that makes the topic model worth the discipline.

The shift is from documents that flow through chapters to topics that get composed into documents. A writer in a chapter-based world drafts chapter 4 of the user guide. A writer in a topic-based world drafts a topic about a specific procedure that might appear in the user guide, in the training material, in the API documentation, and in the help system, possibly all at once, possibly with profiling that surfaces it differently to different audiences.

This is a writing discipline, not a tooling decision. The tooling (DITA, a CCMS, the DITA Open Toolkit) implements the discipline. Without the discipline, the tooling holds components that are nominally independent but actually full of hidden dependencies that break when the components are reused.

DITA’s three topic types

DITA formalizes topic-based authoring into three topic types that cover most documentation needs.

Concept. Explains an idea. What something is, why it matters, how it relates to other things. The “what” and “why” content. A concept topic answers a question like “what is a CCMS” or “why does single source of truth matter”. Concept topics are typically the highest-traffic content in technical documentation because they are also what marketing pages and AI-assistant answers tend to draw from.

Task. Describes a procedure. The ordered steps to accomplish a goal. The “how” content. A task topic answers a question like “how do I configure SSO” or “how do I submit a labeling supplement to FDA”. Task topics have strict structure in DITA: prerequisites, context, steps, result, example. The structure is load-bearing, it makes task topics easy to compose into different procedures and easy for AI assistants to extract step-by-step answers from.

Reference. Provides lookup information. Parameters, error codes, specifications, glossary entries. The “what are the options” content. A reference topic answers a question like “what error codes does the API return” or “what dose forms does IDMP recognize”. Reference topics are typically the densest content and the content most likely to be queried by downstream automation.

Most technical documentation can be expressed cleanly in these three types. The DITA standard allows specialized topic types (troubleshooting, glossary entries, learning objects, controlled-vocabulary entries) for cases where the base three are not enough. Specialization is powerful but adds complexity; we generally recommend exhausting the base three before introducing specialized types.

What changes about how writers work

Three habits change when a team moves from chapter-based to topic-based authoring.

No assumed continuity. Chapter-based writers can write “as we saw in the previous chapter” or “this section builds on the discussion in section 2.3” with confidence that the reader has just read the referenced material. Topic-based writers cannot. The topic might appear first in one document and fifth in another. The continuity has to be explicit: a link to the referenced topic, a brief restatement of the prerequisite concept, or a deliberate decision that the topic only makes sense in a specific context.

The honest reflex is to feel like you are repeating yourself when you re-state the context. The honest answer is that you are not repeating, you are making the topic independent. Without the restatement, the topic only works in the context the writer happened to imagine first.

Explicit links instead of implicit cross-references. “See chapter 4” stops working because the topic might not be in a document that has chapter 4. “See the configuration topic” works, because the link resolves to the same target topic regardless of which document the linking topic appears in. The DITA xref element and the cross-reference resolution at publishing time handle the mechanics.

Thinking in reuse contexts. The topic about “how to configure SSO” might appear in the system administrator guide, in the security configuration guide, in the new-tenant setup checklist, in the training material, and in the help system. The writer has to ask: what context-dependent language has to come out so this topic makes sense in all five? The audience assumption “you are reading the security configuration guide” might be true in one context and false in four. The topic has to work without that assumption.

This is the discipline that takes the longest to internalize. The DITA mechanics are learnable in a week. The reflexes are slower. The fastest path we have seen is pair-writing, a writer used to topic-based authoring sits with a writer transitioning from chapter-based authoring, and reviews each draft for the assumed-continuity reflex. Three months of pair-writing usually settles the habits.

The common failure modes

Hidden dependencies. Topics that look independent but depend on each other in ways the writer did not notice. The classic example: topic A introduces a term, and topic B uses the term without definition. In the source document where the writer drafted both topics, the reader has read A before B. In a derivative document that includes B but not A, the reader has not. The term appears undefined.

Spot this in a draft by reading each topic in isolation. If the topic uses a term, an acronym, a concept, or a procedure that the topic does not define or link to, that is a hidden dependency. The fix is either to add the definition inline, link to the topic that defines it, or accept that the topic only works in contexts that include the prerequisite.

Topics too long. The writer cannot let go of document structure and packs five logical topics into one. The result reads like a small chapter. It is technically a topic but it is not actually independent, because the five logical sub-topics depend on each other.

Spot this in a draft by counting subjects. A topic should cover one subject: one concept, one task, one reference set. If you can extract three task descriptions from a single task topic, the topic is doing the work of three topics. The fix is to split.

The temptation to write long topics is strongest in writers transitioning from chapter-based authoring, because long topics feel like real writing in a way that short topics do not. The honest answer is that short topics are the unit of structured content; the long-topic instinct is a hangover from the chapter-based world that will fade as the writer sees the reuse benefits.

Audience assumptions. The topic assumes the reader has a specific role, has read the introduction, or has a specific level of expertise. The assumption holds in the document the writer was drafting. It does not hold when the topic is reused in another document for another audience.

Spot this in a draft by reading the topic as if you were a different audience. If the topic says “users with admin privileges can do X” but the topic might appear in a guide for non-admin users, the framing has to change. The fix is usually to refactor the framing rather than to add audience filters; profiling (ditaval) is available but adds complexity that is best avoided where the topic can be neutral on the audience.

The DITA model is the load-bearing half

Topic-based authoring without a structural model is harder than it looks. The writer has to remember the discipline; nothing in the tooling enforces it. The reflex to write continuous prose with assumed continuity is strong, and the failure modes above are the natural consequence of the reflex going unchecked.

The DITA model, and a CCMS that enforces it, handles the enforcement half. Topic types impose structural constraints (a task topic has to have steps; a concept topic cannot have steps). Content references make the dependencies explicit rather than implicit. Maps assemble the topics into documents in ways that surface ordering decisions for the writer to make consciously.

This is half of why most serious topic-based authoring lands in DITA. The other half is the ecosystem (the tooling, the patterns, the trained writers) that has built up around DITA over twenty years.

For the underlying CCMS architecture that makes topic-based authoring practical at scale, see the CCMS pillar page. For the writing-tool half of the picture in environments standardized on Microsoft, the case for Word as the authoring surface is in Structured authoring in Microsoft Word, without a separate platform and the practical SME view is in DITA without an XML editor.

Where to start

Three concrete moves for a documentation team starting on topic-based authoring.

Pick one document. Take an existing chapter-based document (a user guide, an SOP, a labeling section) and convert it. Split into topics. Identify the cross-document reuse opportunities. Write the topics independently. Compose them back into the original document and check that it still reads coherently. The exercise reveals where the chapter-based assumptions were hiding.

Read each topic in isolation. Make this a writing-review habit. Every topic in a review gets read out of context, without the surrounding document. If the topic does not stand alone, the topic is not yet independent.

Pair-write. New writers pair with experienced topic-based writers for the first three months. The reflexes from chapter-based authoring are deep and the pair-writing review catches them faster than self-review.

The discipline takes longer to embed than the tooling does to install. The reward is the four payoffs of single source of truth in a CCMS, translation cost, audit response time, regulatory consistency, downstream automation, payoffs that all depend on the components actually being independent.