|
PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
|
|
Loading...
Searching...
No Matches
|
PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
|
|
Every documentation page serves exactly one reader intent. Mixing intents is the main reason a documentation set feels simultaneously bloated and unhelpful: a tutorial that grows into a reference stops being followable, and a reference that accumulates advice stops being scannable.
This page defines the four content types and one structural type, what each owes the reader, and what each must refuse to do.
| Type | Reader intent | Shape |
|---|---|---|
| Tutorial | "Teach me by doing" | Ordered steps, one verified path, guaranteed to work end to end |
| How-to | "Help me accomplish X" | Task recipe, assumes competence, may branch on situation |
| Reference | "Tell me exactly what X is" | Exhaustive, structured, consultable in any order |
| Explanation | "Help me understand why" | Discursive, motivates design, discusses trade-offs |
| Hub | "Where do I go for X" | Structural only: owns the @subpage hierarchy and routes; carries no reference prose of its own |
The first four are content types and describe what a page teaches. Hub is a fifth, structural type: it exists because the navigation tree is built from the @subpage hierarchy, so some page must own that structure. A hub is judged by whether its routes are complete and current, not by what it explains.
Every published page is assigned exactly one of these types in tests/tooling/page_types.json. The registry is central rather than per-page so that typing 71 pages costs no visible chrome on any of them; a page may still declare its type inline with @pagemeta, and where both exist make audit-page-types requires them to agree.
Tutorial owes a working outcome. Every command must run as written, in the order given, from a stated starting state. It states its outcome up front and what success looks like at the end. It links out for depth rather than explaining inline. If a step can fail commonly, it names the failure and the fix.
How-to owes a completed task. It assumes the reader can already run PICurv and wants a specific result. Unlike a tutorial it may branch, and it need not be exhaustive about alternatives - it recommends one route.
Reference owes accuracy and completeness within its declared scope. It is consultable, not readable: structure, tables, and predictable ordering matter more than prose flow. Where a generated artifact exists, reference embeds or defers to it rather than restating it by hand.
Explanation owes understanding. It may discuss history, alternatives considered, and known limitations. It is the correct home for "why is it like this" and for scientific formulation.
make audit-docs-expansion now rejects it by exact signature.Pages 42 and 43 declare type Hub and are judged by the Hub rules above: they own the @subpage structure the navigation tree renders, and they stay lean. A hub that starts restating reference prose has become a duplicate of the pages it routes to.
Page 41 is deliberately not a hub. It declares Tutorial, because it now carries a runnable first-run path rather than only routing. It also adopts subpages, which is allowed: owning hierarchy is a hub's only job, not its exclusive privilege.
Where a page genuinely needs two types, prefer splitting. Where splitting would scatter a single coherent contract across pages, keep it whole and say so.
make audit-page-types fails when a published page has no assignment, when an assignment names a type outside the five, when a page's inline @pagemeta disagrees with the registry, or when the registry types a page that no longer exists. Coverage is measured against the pages the build actually publishes, so a page added without a type cannot certify. The audit runs in make certify-docs and in CI.
The registry types the type; it cannot judge the shape. Whether a page assigned Reference actually reads as reference is a review question, and ยง3 is the standard that review applies.
1.9.8