Table of Contents

Documentation Ownership

This page defines the documentation ownership contract across AsiBackbone/AsiBackbone, AsiBackbone/Learning, and the downstream AsiBackbone/ReferenceApplication. The goal is to keep one canonical educational source, one canonical product-implementation source, and one concrete integration record without allowing them to drift into competing authorities.

Important

AsiBackbone/AsiBackbone remains authoritative for the released product. AsiBackbone/Learning is authoritative for organization-level education and architecture teaching. AsiBackbone/ReferenceApplication is authoritative only for its own host-specific code, generated API reference, and ordered NCAT-to-AsiBackbone integration walkthrough. The Reference Application does not define or override package APIs, NCAT behavior, general architecture guidance, compatibility, security posture, or release behavior.

Canonical sources

Ownership matrix

Documentation type Source of truth
Organization-level concepts and education Learning
Architecture tutorials and tradeoff analysis Learning
Canonical educational definitions and glossary Learning
Terminology lineage and established-concept mapping Learning
Exact terminology-to-API/type mappings AsiBackbone
Labs and general teaching samples Learning
General AI/governance education Learning
Package installation and configuration AsiBackbone
Public API/type behavior AsiBackbone
Package-specific quickstarts and compile-ready examples AsiBackbone
Runtime semantics and integration boundaries AsiBackbone
Security/cryptographic implementation posture AsiBackbone
Provider/package operational guidance AsiBackbone
Release notes, compatibility, migration, consumer verification AsiBackbone
Quality, benchmark, release-readiness, maintainer evidence AsiBackbone
Ordered NCAT-to-AsiBackbone integration walkthrough ReferenceApplication
ReferenceApplication host-specific API and implementation record ReferenceApplication

Sample and tutorial boundary

The ownership matrix above is applied concretely in Sample Ownership and Implementation Boundary. That page classifies the current quickstarts, runnable sample hosts, public API examples, templates, and integration scenarios.

Use the Learning executable sample catalog for standalone teaching samples, labs, exercises, and vendor-neutral runnable examples. Use this repository for examples whose purpose is to exercise the shipped AsiBackbone packages and APIs.

Routing rule for new documentation

Use this test before creating or expanding a page:

If the page primarily teaches a general architectural idea, comparison, tradeoff, pattern, or exercise that remains useful without the AsiBackbone packages, it belongs in Learning. If it primarily documents what a concrete AsiBackbone package, API, configuration surface, runtime path, provider, or release actually does, it belongs in AsiBackbone.

For mixed topics, keep the exact implementation contract and compile-ready product usage in AsiBackbone, link to Learning for the broader explanation, alternatives, or teaching material, and use ReferenceApplication when the purpose is to show the ordered integration of NCAT and AsiBackbone in that concrete host. Do not maintain independent canonical explanations of the same product or general concept.

Moving educational authority to Learning does not mean removing the established AsiBackbone URL.

For a page that becomes Learning-owned:

  1. Keep the existing AsiBackbone path published when practical.
  2. Replace the old body with a short transition or product-boundary page.
  3. State the canonical Learning destination explicitly.
  4. Keep concrete AsiBackbone implementation/API links on the transition page when they remain useful.
  5. Point Learning directly to the relevant product, API, release, or implementation destination. Do not point Learning back to a transition page in a way that creates a circular redirect/pointer pattern.

The curated continuity contract is stored in eng/docs/cross-repository-links.json. It records:

  • preserved transition-page paths and their canonical Learning destinations;
  • critical published Learning and AsiBackbone destinations;
  • the current release-notes and consumer-verification pages, declared once among the local DocFX outputs and once among the published destinations with currentReleaseDocument set to release-notes or consumer-verification;
  • selected reciprocal Learning-to-AsiBackbone links that must remain present.

Any other entry that targets a version-specific release-notes or consumer-verification page must declare "historical": true, so an undeclared versioned page cannot silently stand in for the current release.

After building the DocFX site, run:

./scripts/Validate-DocumentationLinks.ps1

The validator confirms that transition source files still name the canonical Learning target, the old DocFX output paths still exist, critical published destinations resolve, and selected reciprocal links remain present. It also reads publication.latestPublishedVersion from eng/documentation-release-claims.json and fails when a current release destination's path, URL, or label names any other version, or when the local and published current destinations disagree. A current published destination that does not resolve yet is reported as a warning rather than a failure only when this DocFX build contains the matching page, which covers the window between merging a release-preparation change and deploying the site that publishes it. Stable release validation and the documentation publishing workflow run the same guardrail, and ./scripts/Test-DocumentationLinks.ps1 exercises the current-release rules against fixtures.

Authority when content overlaps

Use the product repository as the controlling source for:

  • package IDs, supported target frameworks, installation, and configuration;
  • public types, members, signatures, defaults, reason codes, and serialized behavior;
  • runtime policy, acknowledgment, capability, audit, outbox, signing, verification, and host-integration semantics;
  • security and cryptographic implementation posture;
  • provider status, operational requirements, compatibility, releases, migrations, and consumer verification;
  • quality, benchmark, release-readiness, and maintainer evidence.

Use Learning as the controlling source for:

  • organization-level terminology and concept explanation;
  • architecture tutorials, pattern education, alternatives, and tradeoff analysis;
  • vendor-neutral comparisons and established-concept mapping;
  • labs, exercises, and general teaching samples;
  • general governed-execution and AI/governance education.

A Learning example may point to AsiBackbone as a concrete implementation, but the example does not redefine the product contract. Conversely, product documentation should link to Learning for deeper general education rather than growing a parallel curriculum.

Scope

This contract governs documentation placement and authority only. It does not change runtime behavior, public APIs, package versions, release status, or host responsibilities.