Page taxonomy framework

Frontmatter

Key

pageType: [landing, overview, tutorial, quickstart, how_to, concept, reference, faq, troubleshooting, changelog, glossary, guide] audience: [developer, gateway-operator, orchestrator, delegator, platform-builder, community, internal, general, everyone] TBD: (opt) persona: developer [], gateway-operator [], orchestrator [solo operator, pool operator, new node runner, production operator], delegators [], platform-builder [], community [], internal [], general [], everyone [] purpose: orient, explain, choose, start, build, configure, operate, troubleshoot, optimize, integrate, verify, compare, reference, learn, update complexity: beginner, intermediate, advanced lifecycleStage: discover, evaluate, setup, build, operate, troubleshoot, optimise

• pageType should guide structural fit Example: reference can be more literal; concept should name the idea cleanly; how_to should sound task-oriented.

• purpose should guide the title’s job Example: compare may allow contrast framing; explain should prefer concept labels; choose should help orient a decision.

• audience should guide terminology and specificity Example: technical audiences may support more specialized language; broad audiences may need clearer plain-language titles.

Values

pageType “format”

Domain: Presentation / IA Definition: Presentation Contract Decription: what it does Defines: How is this page structured? Governs:

1. Structural Format & Page Taxonomy
2. UX
3. Success Metrics

• Time to do x

4. Outcome Type / Success Metrics Defines: How is this page structured? Categories:

• landing
• overview
• tutorial
• quickstart
• how_to
• concept
• reference
• faq
• troubleshooting
• changelog
• glossary
• guide

audience “who”

Domain: Reader segmentation Definition: Intended reader class Description: Who this page is for Defines: Governs:

1. terminology
2. assumptions
3. framing
4. examples
5. depth Governs:
6. Content Voice / Language
7. Content Terminology Categories: audience:
8. developer
9. gateway-operator
10. orchestrator
11. delegator
12. platform-builder
13. community
14. internal
15. general
16. everyone

purpose “why”

Domain: Content Strategy / Reader Intent Definition: Content Intent Decription: why it exists Defines: What should this page help the reader do, decide, understand, or find? Governs:

1. Content Need
2. Content (audience) Outcomes Current Categories: purpose:
3. landing
4. overview
5. concept
6. how_to
7. tutorial
8. reference
9. faq
10. glossary
11. changelog
12. troubleshooting Categories:

• orient → help user understand where they are / what exists
• explain → clarify a concept or system
• choose → support a decision
• start → get going quickly
• build → create or implement something
• configure → set up options/parameters
• operate → run/manage in practice
• troubleshoot → diagnose/fix problems
• optimize → improve performance/cost/reliability
• integrate → connect with other systems/tools
• verify → validate setup, behavior, or results
• compare → distinguish between options/models/paths
• reference → look up exact facts/syntax/values
• learn → learn terminology/foundations
• update → communicate changes/new features Enum: [ “orient”, // help user understand where they are / what exists “explain”, // clarify a concept or system “choose”, // support a decision “start”, // get going quickly “build”, // create or implement something “configure”, // set up options/parameters “operate”, // run/manage in practice “troubleshoot”, // diagnose/fix problems “optimize”, // improve performance/cost/reliability “integrate”, // connect with other systems/tools “verify”, // validate setup, behavior, or results “compare”, // distinguish between options/models/paths “reference”, // look up exact facts/syntax/values “learn”, // learn terminology/foundations “update” // communicate changes/new features ]

Title

hello

Components

Layout Tabs, Code groups, Steps, Columns, Panel Use these when the job is to structure the page, sequence information, or present parallel content cleanly.

Disclosure & context control (gah no.) Accordions, Expandables, View, Tooltips Use these when content should be progressively revealed, conditionally shown, or tucked behind lightweight contextual help.

Attention & status signals Banner, Callouts, Badge, Update Use these when the job is to highlight urgency, importance, state, freshness, or inline metadata.

Reference & executable documentation Fields, Response fields, Examples, Prompt Use these for structured technical documentation: inputs, outputs, examples, and copyable AI prompt patterns.

Navigation & visual meaning Cards, Tiles, Frames, Icons, Mermaid, Color, Tree Use these when the job is to route users elsewhere, add visual hierarchy, or represent systems, structures, assets, or relationships.