Navigation crosswalk

Track where legacy documentation pages now live in the Standard-004 audience-first information architecture. Update this checklist whenever a page moves or is retired.

Status note: Last updated 2025-11-10 · Per Standard-004 (Documentation Audience Standard) · Supersedes ADR-022.

Legacy → New location mapping

Legacy page	New location	Notes
calibrated_explanations.rst (legacy landing page)	:doc:../../index	Landing narrative split into role-based overview and section toctrees with audience-first callouts.
getting_started.md	:doc:../../get-started/index with :doc:../../get-started/installation, :doc:../../get-started/quickstart_classification, :doc:../../get-started/quickstart_regression, :doc:../../get-started/troubleshooting	Content decomposed into dedicated installation, runnable quickstarts, and troubleshooting checklists.
practitioner_guide.md (legacy)	:doc:../../practitioner/index with :doc:../../practitioner/playbooks/index and :doc:../../practitioner/advanced/index	Practitioner core and advanced workflows split: core focuses on factual/alternative explanations; advanced collects optional telemetry and performance tooling.
researcher_guide.md (legacy)	:doc:../../researcher/index with :doc:../../researcher/replication/index and :doc:../../researcher/advanced/index	Research content consolidated: replication workflows, benchmark manifests, and literature map in one hub with advanced observability extras.
contributor_guide.md (legacy)	:doc:../../contributor/index with :doc:../../contributor/plugin-contract and :doc:../../contributor/extending/guides/index	Contributor paths split: plugin contract first (core requirement), then extending guides for CLI and configuration surfaces.
viz_plotspec.md	:doc:../how-to/plot_with_plotspec	PlotSpec guidance converted to a how-to focused on configuration plus telemetry links. Practitioner playbooks reference this for advanced visualization.
architecture.md	:doc:../concepts/index, :doc:../concepts/alternatives, :doc:../concepts/probabilistic_regression	Architecture material split into focused concept pages; optional telemetry moved under :doc:../governance/optional_telemetry so provenance scaffolding is clearly opt-in.
(new) interpretation guide	:doc:../how-to/interpret_explanations	Primary resource for reading factual and alternative explanations, PlotSpec visuals, and telemetry provenance. Linked from all quickstarts.
plugin_guide.md (legacy)	:doc:../../contributor/plugin-contract with :doc:../../contributor/extending/guides/index and :doc:../../appendices/external_plugins	Plugin contract elevated in contributor hub; extending guides for wiring CLI and config; external plugin index (community plugins) moved to appendices.
pr_guide.md	:doc:../governance/pr_guide and :doc:../governance/section_owners	Governance actions captured under maintainership docs with owners and release narrative under shared foundations.
(new) migration guides	:doc:../../migration/index	Terminology changes, breaking changes, and upgrade guidance captured in a dedicated section linked from all audience hubs.

Audience-first structure verification

Per Standard-004, the documentation now follows an audience-led structure:

• [x] Getting Started appears first in the main toctree (:doc:../../get-started/index``)

• [x] Practitioner hub includes core workflow (quickstarts → interpretation) and advanced extras (telemetry, performance, PlotSpec)

• [x] Researcher hub consolidates theory, replication, and benchmarks with equal coverage for classification and regression

• [x] Contributor hub foregrounds plugin contract and extending guides; defers optional telemetry/performance to advanced section

• [x] Shared Foundations (concepts, how-to, reference, governance) linked from all audience hubs

• [x] Appendices & Migration segregated for upgrade guidance and external plugin references

• [ ] Re-run the gating commands in :doc:release_checklist after updating cross-references

Verification checklist

• [ ] Confirm all pages in the mapping table are added to their respective section toctrees

• [ ] Ensure deprecated filenames or redirects point readers to the new audience-first paths

• [ ] Validate that classification and regression parity is maintained across quickstarts and advanced guides

• [ ] Confirm interpretation guides are linked from every quickstart (classification and regression)

Navigation patterns to maintain

When editing audience landing hubs, playbooks, or quickstarts, follow these patterns:

1. Interpretation-first callouts: All quickstarts (classification and regression) link to :doc:../how-to/interpret_explanations immediately after the runnable code block.

2. Parity enforcement: Practitioner and researcher pages must provide equivalent coverage for binary/multiclass classification and probabilistic/interval regression.

3. Research hub references: Audience hubs can point readers to :doc:../../researcher/index in a Resources or Further Reading section to avoid navigation clutter.

4. Plugin boundaries: Contributor and practitioner docs reference external plugins (fast explanations, shap-lime, etc.) via :doc:../../appendices/external_plugins instead of embedding them in the core workflow.

5. Cross-link validation: After structural changes, run sphinx-build -b html -W and check for broken cross-references in the build log.