Documentation Consolidation¶
Editorial workflow — instantiates Accumulation Compaction
Merges scattered, overlapping, and conflicting documents into one authoritative current guide — retiring the originals to an archive and keeping a crosswalk of what folded into what, plus the rationale behind each superseded page.
Documentation Consolidation is the editorial workflow that resolves the confusion of many overlapping documents by merging them into a single authoritative guide. Its defining act is reconciliation: unlike a summary that sits on top of preserved sources, this produces a current source of truth that supersedes the originals. When three setup pages disagree about the same procedure, consolidation does not abstract them — it decides which instruction is correct, writes the one right version, and retires the rest. Because supersession is irreversible in practice — people stop reading the old pages the moment a canonical guide exists — the workflow keeps a crosswalk index of which documents folded into which section, and preserves the rationale behind superseded pages, so a future reader can still ask why the old way was wrong.
Example¶
A platform team's internal wiki has accumulated eleven pages about deploying a service, written by different engineers over four years. Three describe mutually contradictory rollback steps; two reference a tool that was decommissioned; one is authoritative but buried on page nine of search results. New hires follow whichever page they find first, and half of them find a wrong one. The team consolidates. They read all eleven, decide the correct current procedure, and write one deploy guide. The ten superseded pages are moved to an archived namespace and replaced with a redirect. A short crosswalk at the bottom of the new guide records which old pages were merged in and which were retired as obsolete.
Critically, the guide keeps a "why this changed" note explaining that the old blue-green rollback was dropped when the platform moved to canary releases — the rationale that a puzzled engineer would otherwise have to reconstruct from a decommissioned page. Search now returns one correct guide. The old pages still exist for anyone who needs the history, but nobody mistakes them for current instructions.
How it works¶
What distinguishes it from summarizing or archiving alone is the editorial merge that resolves conflict:
- Gather and reconcile. Collect the overlapping documents and decide, page by conflict, which content is current and correct — the judgment step no automated sibling performs.
- Author one authoritative guide. Write a single consolidated document that becomes the source of truth for its topic.
- Retire originals to archive with redirects. Move superseded pages out of the active space and point them at the new guide, so no one lands on stale instructions.
- Keep a crosswalk and rationale. Index which documents folded into which section, and preserve why superseded content was dropped, so the history stays interpretable.
Tuning parameters¶
- Consolidation scope — one topic or a whole documentation set at once. Narrow scope ships a trustworthy guide quickly; broad scope fixes more but risks a stalled, sprawling rewrite.
- Supersession firmness — whether old pages are redirected, archived read-only, or left visible with a banner. Firm supersession prevents confusion but hides history; soft supersession keeps both visible at the cost of ambiguity.
- Rationale depth — how much of the "why it changed" is carried into the guide. Rich rationale prevents relitigating settled decisions but lengthens the guide; thin rationale is lean but forgets its reasons.
- Crosswalk granularity — page-level or section-level mapping of what merged where. Fine mapping makes the merge auditable; coarse mapping is cheaper but harder to trace later.
When it helps, and when it misleads¶
Its strength is that it gives a topic one answer instead of eleven, killing the specific failure where readers act on contradictory or dead documentation. This is the single source of truth principle applied to accumulated docs — one canonical place per fact[1], everything else pointing to it.
It misleads when consolidation flattens genuine, still-valid variation into a false uniformity — merging two procedures that were different for good reason (two environments, two audiences) into one guide that is wrong for both. It also fails when the guide is written but the old pages are left live and unredirected, so the wiki now has twelve documents instead of eleven. And a consolidated guide can ossify: canonized once, never revisited, it slowly drifts from reality with all the authority of a source of truth and none of the accuracy. The discipline is to preserve the rationale so settled decisions need not be relitigated, redirect the superseded pages so the merge actually reduces confusion, and re-consolidate on a real cadence. Reconstituting the full old detail on demand is not this workflow's job — the crosswalk points to the archived version, but making that history a working, restorable artifact is Snapshot Plus Archive.
How it implements the components¶
Documentation Consolidation fills the editorial-merge side of the archetype — turning scattered documents into one current, traceable guide:
summary_layer— the single consolidated guide that becomes the current source of truth for its topic.archive_rule— the retirement of superseded pages to an archived namespace behind redirects.provenance_preservation— the rationale carried forward explaining why superseded content was dropped.layer_index— the crosswalk mapping which original documents folded into which section of the guide.
It does NOT operate a retrieval_path or rehydration_or_rollback_path for reconstituting the old detail on demand — that is Snapshot Plus Archive; the crosswalk names where a superseded page was filed, but the guide, not the archive, is the working artifact.
Related¶
- Instantiates: Accumulation Compaction — it is the archetype applied to accumulated, conflicting documents.
- Consumes: Deduplication Pass — removing exact-duplicate pages first means the editorial merge reconciles genuinely different content rather than re-merging copies.
- Sibling mechanisms: Snapshot Plus Archive · Archival Summarization · Knowledge Base Pruning · Backlog Consolidation · Retrospective Synthesis · Deduplication Pass · Database Vacuum or Compaction · Log Compaction · Retention Schedule
Editorial Notes¶
Form Classification¶
Form family: Intervention, Treatment & Transformation
Rationale: The mechanism directly changes the documentation estate by reconciling overlapping material into one authoritative guide and archiving or redirecting the superseded originals.
Nearest alternative: Protocol, Workflow & Routine — Gathering, reconciling, authoring, and retiring can be sequenced, but success is the transformed authoritative corpus rather than faithful execution of the sequence itself.
Review outcome: Adjudicated after independent review; high confidence.
Origin Attribution¶
Primary origin: Library & Information Science
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Information architecture cohered authoritative-source consolidation, controlled retirement, crosswalks, and provenance for overlapping knowledge artifacts.
Related originating lineages:
- Computer Science & Software Engineering — Software documentation practice established the single-source-of-truth discipline and redirects from stale duplicate pages.
- Organizational & Management Science — Knowledge management supplied ownership, governance, and migration processes for replacing scattered guidance.
Review resolution: Both current reviews place documentation_consolidation primarily in library_information_science; the reconciled classification retains only lineages that materially shaped the mechanism and keeps breadth of origin separate from reach.
Attribution caveat: The single-source-of-truth principle spans information architecture and organizational knowledge management.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; high confidence.
References¶
[1] DAMA International. DAMA-DMBOK: Data Management Body of Knowledge, Second Edition. Technics Publications (2017). Requires one canonical source for each fact. registry ↩