Nexus documentation page templates

Templates list questions every page must answer. Adapt headings to tasks and reuse standards by inclusion/linking. New/changed prose follows content/diagram standards; metadata alone does not establish content quality. Tutorial code comes from verified fixtures or pinned external examples.

1. Tutorial

  1. Goal and expected completed outcome.

  2. Applicable code/SDK version, Board/OS/mode, tools, working directory and equipment prerequisites.

  3. Inputs, configuration and resources; label complete inputs separately from fragments.

  4. One complete path with commands/APIs, expected results and checks for each step.

  5. Diagnosing common rejection/failure while retaining resources.

  6. Shutdown, drain and cleanup; when results/storage may be reused.

  7. Actual validation records and next steps.

Async tutorials link submission/cancellation/drain sequences; external-SDK tutorials link consumer flows. Without equipment, describe software validation/HIL preparation only rather than claiming hardware steps succeeded.

2. How-to

  1. One task and its applicable scope.

  2. Legal Task/IRQ/privilege context, inputs and resource owners.

  3. Shortest complete steps with explicit defaults/exceptions.

  4. Normal results, rejection, timeout/cancel and failure recovery.

  5. Resources returned and responsibilities still retained afterward.

  6. Limitations and authoritative contracts.

Link explanations instead of repeating fundamentals, but never omit lifecycle/concurrency conditions affecting correctness.

3. Reference

Item

Required content

Field/symbol

Exact name, type and authority.

Value

Units, range, defaults and activation conditions.

Combination

Valid/invalid modes, platforms and ABIs.

Call

Context, deadlines and input/output ownership.

Failure

Rejection conditions, state changes, effects and remaining responsibility.

Qualification

Maintained/software/physical scope and evidence entry.

Generate API declarations; manuals never hand-copy competing signatures. Reference complete configurations or explain fragments. Complex controller/endpoint, resource and memory relationships link structural/exact-reference diagrams.

4. Explanation

  1. Problem and constraints.

  2. Current/target structure with diagram identity/sources.

  3. Layer responsibilities, state and resource owners.

  4. Build/runtime stages and distinctions between dependencies, calls and data flow.

  5. Main flows/failure responsibilities; concurrent flows link sequences/state diagrams.

  6. Performance/space costs, tradeoffs and conditions.

  7. Limitations and actual validation scope.

  8. Related contracts, source and how-to guides.

Architecture explanations must include corresponding diagrams; simple facts may reference existing diagrams. Do not redraw equivalent diagrams only to change colors/names. Never merge implementation and target proposals in one unlabeled diagram.

5. Status

  1. Separate identities of described code, documentation and qualified source.

  2. Exact configuration/scope/tools and actual execution.

  3. Retrievable evidence, archives/members and verification.

  4. Implemented, executed, unexecuted, failed or blocked items.

  5. Support/qualification boundaries and next exit conditions.

Never aggregate table numbers across scopes; implemented does not replace software/physical passes. Evidence flows acquire software and HIL independently before joining; software never automatically becomes physical qualification.

6. 每页审查清单

  • Readers, goals, versions and scope are explicit.

  • Steps/rules are actionable/checkable with command prerequisites and expected results.

  • Objects, units, contexts, borrowing, failures and recovery are explicit.

  • Current/target/reference and implementation/software/HIL identities stay distinct.

  • Every diagram entity/edge is explainable and matches source/contracts.

  • Code/configuration examples have actual validation or explicit fragment rationale.

  • Prose, diagrams and translations create no competing standards.

  • References, offline resources, alt/captions and legacy URLs are correct.

  • Findings/fixes bind actual pages/diagrams and source identities.