Skip to content

Content health and governance

Documentation degrades over time. Products change, features get renamed, and workflows evolve. If documentation does not keep up, it becomes a liability rather than an asset. Topicary's content health system makes decay visible so you can address it before readers notice.

Why content decays

Negligence does not cause content decay. It is a natural consequence of how software evolves:

  • A feature gets updated but the docs do not

  • A team member leaves and their section becomes unowned

  • A new product version ships and old docs are not reviewed

  • A component gets deleted but references to it remain

  • A variable set changes but topics still use the old keys

The challenge is not fixing these problems. It is knowing they exist. Most documentation tools give you no signal until a reader reports an issue. By then, trust is already eroded.

Automatic health tracking

Topicary tracks content health continuously across 4 dimensions:

Dimension

What it checks

Signal

Staleness

Time since last update

Flagged at 90+ days

Orphan detection

Topics not in any map

Unreachable content that may be forgotten

Reference integrity

Component, link, and variable references

Broken references cause gaps in published output

Structural validation

Heading hierarchy, empty topics

Skipped headings or empty stubs undermine credibility

Staleness measures time since last update. Topics untouched for 90 or more days are flagged as Stale (90d+) in the Topics list and counted on the dashboard. The nightly health scan uses its own configurable threshold, which starts at 90 days as well. Neither threshold is arbitrary: both are signals that content may not reflect the current product state.

Orphan detection finds topics that are not included in any map. Orphaned topics exist in the project but are not reachable through any published site. They may be drafts, deprecated content, or simply forgotten.

Reference integrity checks that every component reference, topic link, and variable token points to something that exists. Broken references mean readers see gaps or errors in the published output.

Structural validation checks heading hierarchy (no skipping from H1 to H3) and whether topics have content at all. Empty stubs in a published site undermine credibility.

Governance without process overhead

Teams try to solve content decay with process: scheduled review cycles, assigned content owners, mandatory review gates. These processes work but create overhead and become the first thing skipped when deadlines hit.

Topicary's approach is different: make the problems visible and trust authors to act. The dashboard health cards, topic list filters, and validation panel surface issues where you already work. They do not hide in a separate governance tool that nobody checks.

This works because the feedback is:

  • Automatic: no one has to remember to run an audit

  • Contextual: health indicators appear where you are already working

  • Direct: each indicator links directly to the content that needs attention

  • Proportionate: warnings stay out of your way, and only the defects that would break the published page stop a publish

Schedule a content audit before each major product release. Open the validation panel in the map editor to run all checks at once. Then filter the Topics page by health status to create a focused work queue. Addressing staleness and broken references before a release prevents readers from encountering outdated content.

Warnings are not publishing gates, but validation errors are. Publishing a map runs every validation rule first and refuses with "Cannot publish: N validation error(s) found" while any error remains. Broken component references, undefined variables, broken topic links, missing image alt text, draft paragraphs, unresolved suggestions, and conditions that publish to everyone (a condition that never resolved, one that names values the project does not have, or one that selects no values) are errors. Staleness flags, orphans, empty topics, conditions that reference a deleted dimension or deleted values, and structural nits are warnings or information, and never block a publish.

Validation panel in the editor

When editing a map, the Validation panel is accessible from the right icon rail. It runs all content health rules against every topic in the map, by itself the first time you open it and again whenever you select Run validation. Findings are grouped by topic with severity icons (error, warning, info). The panel's badge counts errors and warnings only: information-level findings are listed but never counted, and the badge is hidden when there are none. This gives you a focused view of content quality without leaving the editor.

Structure suggestions

Health checks find decay in individual topics. Structure suggestions work on the level above: they propose organizing changes across the project, such as a tag group for topics that belong together, a topic type, a variable for a repeated value, a condition dimension, or a split of an overloaded map.

They appear in Analytics ▸ Content health, and you accept, edit, dismiss, revert, or restore each one in place. See Review structure suggestions for the review flow.

Content audits

For teams that want periodic structured reviews, use the validation panel in the map editor to run all checks at once and review findings by topic and severity. This is useful before major releases or during quarterly review cycles.

Filter the Topics page by health status to create a focused work queue: all stale topics, all broken references, all empty stubs. Address them in priority order rather than reviewing everything.

See also

See also

Was this page helpful?