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
- Product implementation and API documentation: AsiBackbone documentation and AsiBackbone repository.
- Architecture education and general teaching: AsiBackbone Learning and AsiBackbone/Learning repository.
- Concrete NCAT-to-AsiBackbone integration walkthrough and host-specific API reference: Reference Application documentation and AsiBackbone/ReferenceApplication repository.
- Canonical educational terminology: Learning Architecture Glossary and Terminology and Established Architecture Concepts.
- Product/API terminology mappings: AsiBackbone API Glossary, AsiBackbone API Terminology Map, and Core API Domain Model.
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.
URL continuity and cross-repository link contract
Moving educational authority to Learning does not mean removing the established AsiBackbone URL.
For a page that becomes Learning-owned:
- Keep the existing AsiBackbone path published when practical.
- Replace the old body with a short transition or product-boundary page.
- State the canonical Learning destination explicitly.
- Keep concrete AsiBackbone implementation/API links on the transition page when they remain useful.
- 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
currentReleaseDocumentset torelease-notesorconsumer-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.