Nexus complete documentation-system improvement checklist¶
This page derives from the implementation ledger. That CSV is the sole authority for tasks, dependencies, implementation and acceptance values; status updates do not change original IDs or exit conditions. Source SHA-256: d1f5adad33468cb83c2849b9ec5176d10d958db044620943e93fb0d02d6a2c77. The same generator checks missing/stale views at commit and CI.
Current implementation and acceptance¶
implemented means a page, tool, gate or delivery path exists; development_passed records actual development checks without formal release/exit qualification. pending_formal_evidence awaits exact clean-source, deployment, restoration or independent-review records. See documentation acceptance for actual records/scope and original per-item fields for all states/evidence locations.
Implementation value |
Acceptance value |
Source records |
|---|---|---|
|
|
58 |
Items needing formal evidence, failure or unexecuted review: none pending; interpretation still follows actual evidence scope.
Previews, software models, diagram sources and successful rendering do not replace public deployment, physical HIL or product qualification. Documentation packages and evidence archives bind the same delivery; never invent unacquired digests or locators.
Prioritize P1; P2 is also delivery scope. Codex owns responsibility with independent agent review. New/changed prose follows content/diagram standards and page templates; see the 15 required diagram classes. D1–D6 are dependency-ordered work packages, without aggregating other ledgers’ task or acceptance counts.
D1 Entry points, authorities and prose rules¶
ID |
Priority |
Improvement |
Exit condition |
|---|---|---|---|
DOC-01 |
P1 |
Register page authorities and reader tasks |
Identify authoritative prose, API, support, qualification, ledger and historical sources for every page; directory structure and unique navigation must be reviewable |
DOC-02 |
P1 |
Correct root entries and support statements |
README statements about typed factory, TOML, ThreadX, continuous modes and exact support are consistent; do not expand physical-board scope |
DOC-03 |
P1 |
Correct executable configuration templates |
Board examples include soc_family; complete Board and CPU/TOML inputs are actually parsed; fragments explicitly do not establish complete-configuration qualification |
DOC-04 |
P1 |
Unify latest-qualification navigation |
Current code, documentation HEAD, qualified source and historical records are separately locatable; prior execution is not inherited |
DOC-05 |
P1 |
Map original exit conditions and new evidence for each ledger |
Map OS48 and outdated statuses by scope; retain original IDs, conditions and failed records; do not bulk-mark passed |
DOC-06 |
P1 |
Create migration-reference and legacy-URL inventories |
Every current content source has a destination; relative links, anchors, tool inputs and legacy URLs have complete handling rules |
DOC-41 |
P1 |
Apply prose-writing and semantic standards |
Critical pages specify readers, goals and configurations; terminology, units, normative strength, facts and qualification pass independent review |
D2 Site, architecture and API¶
ID |
Priority |
Improvement |
Exit condition |
|---|---|---|---|
DOC-07 |
P1 |
Select and integrate MyST |
Remain compatible with maintained Sphinx/Breathe; actually build complete positive and negative Markdown/RST fixtures; specify the pin |
DOC-08 |
P1 |
Adjust the Sphinx source root and exclusions |
Use docs as source root and index prose directly; keep archives, generated outputs and large evidence outside the site |
DOC-09 |
P1 |
Implement unique task navigation |
The home page provides use, integration, maintenance, acceptance and migration entries; current pages are reachable and searchable; do not maintain a second copy of prose |
DOC-10 |
P1 |
Reorganize public API and factory explanations |
Core/Arch/I/O/OS/Components module pages link to symbols; factory examples use actual generated interfaces |
DOC-11 |
P1 |
Integrate system contracts and architecture explanations |
Lifecycle and safety restrictions retain their original normative meaning; contracts and explanations each have one authority |
DOC-12 |
P2 |
Integrate source-adjacent READMEs |
Retain the implementation map and local SoC authorities; include-relative references are correct or source links are bound to the site revision |
DOC-43 |
P1 |
Deliver whole-platform architecture and external-boundary diagrams |
Core/Arch/SoC/Board/I/O/optional OS components and external-product responsibilities are clear; distinguish factory interface lookup from direct I/O |
DOC-44 |
P1 |
Deliver the actual compilation-target dependency graph |
Check actual CMake targets and private/public dependencies; vendor implementation remains private; do not treat generation or runtime arrows as compilation dependencies |
DOC-45 |
P1 |
Deliver configuration and generation-flow diagrams |
TOML/facts/typed IR/atomic bundles/CMake/Ninja artifacts and failure invalidation are accurate; do not turn unknown Board facts into known facts |
DOC-46 |
P1 |
Deliver factory and instance-structure diagrams |
Static faces/shared ops/independent contexts and controller/endpoint relationships match source; getters allocate or initialize nothing |
DOC-53 |
P1 |
Deliver software and HIL evidence-relationship diagrams |
Associate source/configuration/tools/receipts with candidate identity; software and HIL evidence are separately acquired through actual execution; no automatic physical qualification |
D3 Tutorials, integration and execution mechanisms¶
ID |
Priority |
Improvement |
Exit condition |
|---|---|---|---|
DOC-13 |
P1 |
Deliver the external SDK introductory tutorial |
A real external consumer at a fixed revision configures, builds and runs or links successfully; retain actual commands and cleanup steps |
DOC-14 |
P1 |
Deliver the async I/O and cancellation-drain tutorial |
Real examples cover reject/accept/cancel/drain/settled/quarantine; borrowed storage is not reclaimed early |
DOC-15 |
P1 |
Deliver the Board-integration guide |
Verifiable templates, route authorization, sources and unknowns are explicit; reuse existing SoCs; separate software and PCB qualification |
DOC-16 |
P2 |
Deliver SoC/provider/component integration guides |
List facts/startup/time/provider/testing/SDK/HIL conditions by vertical slice; generic devices need not enter the generator |
DOC-17 |
P1 |
Deliver OS waiting and shutdown guidance |
Backend semantics, execution progress, actual deletion and storage-reclamation conditions are clear; examples are validated on maintained backends |
DOC-18 |
P1 |
Deliver legacy configuration and interface migration guidance |
Legacy HAL/OSAL/Kconfig has an executable migration path to current TOML/factory; old IDs are not persisted across bundles |
DOC-19 |
P2 |
Deliver configuration and tool references |
Fields, units, rejection rules and CLI come from maintained implementation; do not manually copy API declarations or duplicate configuration authorities |
DOC-20 |
P2 |
Deliver performance-diagnosis and HIL-preparation guidance |
Distinguish ELF budgets, measured cycles, stack and HIL; tool preparation does not claim hardware execution |
DOC-42 |
P1 |
Apply five templates and per-page content review |
Walk through critical tutorial/how-to/reference/explanation/status pages against templates; correct omissions or explain them; metadata does not substitute for acceptable content |
DOC-47 |
P1 |
Deliver initialization, shutdown and failed-start withdrawal diagrams |
prepare/start/stop/withdraw follow the actual selected sequence; partial effects and reverse-order withdrawal responsibilities are explicit; do not start the scheduler automatically |
DOC-48 |
P1 |
Deliver request-state and borrow diagrams |
Separate admission outcomes from enum states; cancellation/deadline retain borrowing; SETTLED and observer/slot-release conditions are explicit |
DOC-49 |
P1 |
Deliver UART and SPI DMA execution sequences |
Show normal and cancellation/drain-failure paths for selected modes; separate Task/IRQ/DMA domains and DMA TC/wire complete/SETTLED |
DOC-50 |
P1 |
Deliver wait/wake and OS-shutdown diagrams |
ready-arm-ready-wait-ready, deadlines and execution-progress responsibilities are accurate; reclaim storage only after actual join/delete |
DOC-51 |
P1 |
Deliver memory, DMA and Cache reference diagrams |
Specify exact chip/mode/memory domain/reachability/alignment and whole-line maintenance; do not infer DMA or coherence from a CPU name |
DOC-52 |
P1 |
Deliver Source SDK consumption-flow diagrams |
Separate actual relocated external consumers from source-tree self-tests; accurately state configuration/build/run-or-link scope |
DOC-55 |
P2 |
Deliver Cortex-M capability-layer diagrams |
Separate CPU primitives/Runtime/SoC/Board/HIL; FPU/MVE/Cache/security capabilities and actual ports do not inherit qualification from one another |
DOC-56 |
P2 |
Deliver the U575 synchronous two-domain reference diagram |
Limit scope to an independent TZEN1 synchronous no-OS reference; define SAU/MPU/GTZC/gateway and seal-failure responsibilities; no general NS RTOS/async claim |
DOC-57 |
P2 |
Deliver continuous-stream and visible-loss diagrams |
producer/block/consumer/loan/overrun/stop are accurate; service and capacity conditions are explicit; do not promise unconditional zero loss |
D4 Bilingual content, diagrams and reader review¶
ID |
Priority |
Improvement |
Exit condition |
|---|---|---|---|
DOC-21 |
P1 |
Define bilingual terminology and release-critical pages |
Original languages and nontranslatable identifiers are explicit; fix critical-page scope; do not require duplicated CSVs or raw logs |
DOC-22 |
P1 |
Implement gettext and translation-source revision checks |
Use one translation chain; build English and Chinese originals into en/zh_CN respectively; mark missing fallback and stale/fuzzy according to actual prose language and source revision |
DOC-23 |
P1 |
Complete bilingual review of critical use paths |
Independently review critical introductory, configuration, factory, borrow, support, qualification and migration prose; do not falsely report missing languages as complete |
DOC-24 |
P1 |
Show actual page language and translation status |
reviewed/stale/missing/original are visible on pages and entry points; English fallback is not marked as translated Chinese; locale does not override source_language |
DOC-25 |
P2 |
Organize local diagrams and offline resources |
Diagram sources are reviewable and arrows agree with contracts; images/fonts/scripts do not depend on CDNs; lock new rendering tools; pair DOT/SVG; lock Graphviz and actual fonts; SVG has no external resources/scripts/DOCTYPE |
DOC-26 |
P1 |
Complete reader-task walkthroughs |
An independent agent completes tasks from their entry points; correct bad steps, inaccessible contracts and revision confusion; record actual results; independently review semantics against content standards |
DOC-58 |
P1 |
Execute diagram/prose consistency and visual/offline review |
Check every edge and state against sources; include sources/outputs/alt/captions; check SVG-safe resources and fonts; actually verify desktop/narrow-screen zoom/print/offline; do not mark unexecuted checks passed |
D5 Tools, gates and CI¶
ID |
Priority |
Improvement |
Exit condition |
|---|---|---|---|
DOC-27 |
P1 |
Unify the docs CLI and legacy-script forwarding |
check/build/preview/package/doctor have clear purposes; local and CI strict arguments match; preserve failure codes and diagnostics |
DOC-28 |
P1 |
Create offline link, anchor and navigation checks |
Deliberately bad files/anchors/duplicate IDs/unreachable pages actually fail; legal cross-page references and migration aliases actually pass |
DOC-29 |
P1 |
Expand actual configuration-fragment validation |
New paths, RST, complete Board and CPU inputs pass the actual resolver; syntax fragments do not gain executable qualification |
DOC-30 |
P1 |
Associate executable code and consumers |
literalinclude sources and test identities are traceable; maintained examples actually build; do not arbitrarily execute documentation shell text |
DOC-31 |
P2 |
Create bounded external-link checking |
Report 404/revision mistakes separately from network failures; bound timeout/retry; commits require no network by default |
DOC-32 |
P1 |
Integrate documentation commit and strict CI gates |
Execute fast offline commit checks and complete documentation CI; apply TDD to negative tool paths; prose changes do not fabricate firmware acceptance; machine diagram-resource checks and prose/diagram semantic review have explicit separate responsibilities |
DOC-33 |
P1 |
Lock and actually install the documentation-tool closure |
Lock all transitive Python wheel hashes and Doxygen identity; actually install/build at a clean maintained tuple; actually verify Graphviz and font closure |
DOC-34 |
P1 |
Separate preview builds from publication permissions |
PR artifacts carry source identity; trusted deployment consumes only verified outputs; do not execute external PR source with elevated privileges |
D6 Publication, restoration and migration closure¶
ID |
Priority |
Improvement |
Exit condition |
|---|---|---|---|
DOC-35 |
P1 |
Generate version and qualification manifests |
Read platform version from existing policy; separate code/docs/qualified source; outputs list payload only; exclude manifest/checksums/archive and indirect hash self-reference |
DOC-36 |
P1 |
Generate relative-link offline HTML packages |
Include languages/API/manifest/checksums/licenses; browse and verify outside the workspace; avoid hash self-reference |
DOC-37 |
P1 |
Publish immutable versions and the stable entry |
Bind release-id to a manifest without overwrite; actual deployment succeeds; stable does not claim all HIL passed |
DOC-38 |
P1 |
Execute post-publication site and download verification |
Online identity matches the deployed package; critical pages, legacy URLs, diagrams and downloads pass checks; old APIs are not silently mapped to new contracts |
DOC-39 |
P1 |
Complete independent recovery and long-term storage |
Stable acquisition locations and retention policy are explicit; restore, browse and verify in an independent root; remote recovery must actually execute |
DOC-40 |
P1 |
Close migration and independently review delivery |
All mappings handled; no duplicate standards, broken links or incorrect qualification; original evidence retained; all 58 tasks and 15 required diagram classes meet exit conditions; unclaimed configurations, HIL and later extensions retain accurate boundaries |
DOC-54 |
P2 |
Deliver release and independent-recovery diagrams |
Documentation/SDK/archive channels and identities are accurate; distinguish targets from actual publications; clarify independent acquisition/recovery/verification boundaries |