When to do this
After all Learn Hub migration batch PRs (#209–#217 and any remaining) merge to infra/learn-hub-migration-prep. This is a single audit pass across the full site, not something individual batch PRs can do in scope.
Sub-tasks
1. Content placement audit
Review every page for content that belongs in a different section. For each misplaced section, move the content or extract it to the right page. Concrete known case:
references/system-canisters.md contains a "Using system canisters" section with code examples (Motoko + Rust). This is guide content sitting in a reference page. Either extract to a guide or remove it if covered elsewhere.
Apply the Diataxis test to everything: guides answer "how do I?", concepts answer "what is it and why?", references answer "what are the exact details?". Content that fails the test for its current page needs to move.
2. Technical term first-use linking
Walk every page and verify that technical terms are linked or explained on first use. Terms that already have a concept or glossary page should be linked when first mentioned. This is distinct from #218 (which focuses on inbound links to new pages, not first-use correctness within pages).
3. Glossary gaps
Compare terms used across the docs against references/glossary.md. File additions for any significant terms that are used repeatedly but not defined.
4. Concepts sidebar subsections
The Concepts section currently has ~20 flat items with two nested groups (Protocol Stack, Chain Fusion). Now that the migration has added pages for economics, cryptography, ledgers, security, governance, and infrastructure, grouping makes sense. Proposed grouping:
- Infrastructure: Network Overview, Canisters, App Architecture, Node Infrastructure, Edge Infrastructure, Evolution & Scaling, Protocol Stack
- Core capabilities: Cycles, Orthogonal Persistence, HTTPS Outcalls, Verifiable Randomness, Timers
- Cryptography & cross-chain: Chain-Key Cryptography, Certified Data, Chain Fusion, VetKeys
- Economics & governance: Network Economics, Ledgers, Security Model, Governance
This grouping should mirror how concepts/index.md already organises the pages.
5. Slug / URL structure review
With ~20 concept pages now live, check whether any slugs are ambiguous, too generic, or inconsistent with the naming conventions established in the migration. Flag any that should be renamed (with redirects).
6. Sidebar top-level ordering
See #225 for the Languages + Developer Tools repositioning (can ship earlier). The holistic review should confirm the final order is correct once all sections are populated.
Related issues
When to do this
After all Learn Hub migration batch PRs (#209–#217 and any remaining) merge to
infra/learn-hub-migration-prep. This is a single audit pass across the full site, not something individual batch PRs can do in scope.Sub-tasks
1. Content placement audit
Review every page for content that belongs in a different section. For each misplaced section, move the content or extract it to the right page. Concrete known case:
references/system-canisters.mdcontains a "Using system canisters" section with code examples (Motoko + Rust). This is guide content sitting in a reference page. Either extract to a guide or remove it if covered elsewhere.Apply the Diataxis test to everything: guides answer "how do I?", concepts answer "what is it and why?", references answer "what are the exact details?". Content that fails the test for its current page needs to move.
2. Technical term first-use linking
Walk every page and verify that technical terms are linked or explained on first use. Terms that already have a concept or glossary page should be linked when first mentioned. This is distinct from #218 (which focuses on inbound links to new pages, not first-use correctness within pages).
3. Glossary gaps
Compare terms used across the docs against
references/glossary.md. File additions for any significant terms that are used repeatedly but not defined.4. Concepts sidebar subsections
The Concepts section currently has ~20 flat items with two nested groups (Protocol Stack, Chain Fusion). Now that the migration has added pages for economics, cryptography, ledgers, security, governance, and infrastructure, grouping makes sense. Proposed grouping:
This grouping should mirror how
concepts/index.mdalready organises the pages.5. Slug / URL structure review
With ~20 concept pages now live, check whether any slugs are ambiguous, too generic, or inconsistent with the naming conventions established in the migration. Flag any that should be renamed (with redirects).
6. Sidebar top-level ordering
See #225 for the Languages + Developer Tools repositioning (can ship earlier). The holistic review should confirm the final order is correct once all sections are populated.
Related issues