Authoring Guide

Write one readable authority, identify what each claim contributes, and use native citations.

This is the contributor reference, not a prerequisite for reading the Knowledge catalog. Preserve one owner for each explanation. Package-version resources own public model/API/use/result semantics; cross-package Knowledge explains relationships and project reasoning.

Documentation Style v1 — Direct, Physical, Auditable

A Knowledge page succeeds when a new reader can answer four questions without reverse-engineering the prose:

  1. What physical system or engineering question is being discussed?
  2. What quantities, basis, boundaries, and conventions are the inputs?
  3. What physical assumption or mathematical operation changes those inputs?
  4. What result comes out, and what may that result be used for?

Choose the document role first

Pages do not share one universal teaching template. Choose the role that matches the reader’s task, then use the smallest structure that completes that task.

Every Knowledge node begins with the same two-line identity:

**Node role:** Procedure.
**Reader task:** Carry one declared input to one named output.
Role Reader task Main-text spine What stays out of the spine
Procedure Carry one declared input through a repeatable sequence to a named output. Purpose and prerequisites \(\rightarrow\) ordered steps \(\rightarrow\) assumptions and diagnostics \(\rightarrow\) handoff. Alternative routes, implementation history, and long special cases.
Concept Understand one physical distinction, definition, or causal relationship. Question \(\rightarrow\) definition \(\rightarrow\) minimum derivation \(\rightarrow\) physical consequence \(\rightarrow\) common confusion. Workflow details and target-specific acceptance rules.
Method Apply a mathematical or numerical operation to a declared physical object. Allowed claim \(\rightarrow\) required inputs \(\rightarrow\) model or algorithm \(\rightarrow\) residual and interpretation \(\rightarrow\) failure modes. Physical ownership that the method cannot establish.
Worked Example See one Procedure or Method executed on a concrete topology. Inherited contract \(\rightarrow\) concrete system and basis \(\rightarrow\) complete execution \(\rightarrow\) closure tests. Re-definitions of the general rule and unrelated device variants.
Design Target Decide whether one design satisfies an engineering goal. Goal \(\rightarrow\) target quantities \(\rightarrow\) constraints and costs \(\rightarrow\) validation evidence \(\rightarrow\) decision. Reusable derivations already owned by Knowledge nodes.

A page may use supporting material from another role, but one role owns its main spine. For example, a Method may link to a Concept for pole semantics and to a Worked Example for a device-specific fit; it should not reproduce either page.

Start with the shortest complete route

The first screen should state the page’s job and show a short, complete main route. Start from the physical question, not from historical context, notation trivia, or a general formalism.

Each main step must have this shape:

\[ \boxed{ \text{declared input} \longrightarrow \text{one operation or assumption} \longrightarrow \text{named output}. } \]

The next step must use that output. If a detail is not used by the main route, delete it, link to its canonical node, or place it in a collapsed callout.

Keep physics and mathematics separate

Layer Examples Rule
Physical model Conductors, branches, fields, ports, losses, terminations, and circuit topology State what physically exists before writing a matrix.
Boundary or approximation Zero pad charge, lossless model, rotating-wave approximation, fitting window State it at the equation where it first changes the result.
Mathematical tool Coordinate transform, Schur complement, diagonalization, interpolation, or fitting Say exactly which declared object it acts on.
Result Reduced matrix, Hamiltonian coefficient, network response, fitted parameter, or pole State its basis, units, provenance, and allowed role.

A mathematical tool may transform or estimate a physical model. It may not invent a coupling, basis, boundary condition, or parameter meaning that the physical model did not supply.

Name coordinates and bases only when they exist

  • Define a vector’s ordering before using a matrix that acts on it.
  • Keep the same physical symbol while the physical quantity remains the same. Node or generalized flux stays \(\Phi\); use subscripts and superscripts to identify its coordinate set.
  • Introduce a new basis name only after writing the transformation or reduction that creates it.
  • Never add, compare, or diagonalize matrices expressed in different bases.
  • Define units and conventions at first use, or link directly to the canonical convention node.

Write equations as a connected derivation

Define a symbol once in a LaTeX equation. Use prose for its physical meaning; do not repeat the same definition in words. Use $...$ for inline mathematics and a display equation when the definition is part of the page contract.

Do not drop a final formula into the page without showing where its inputs came from. Immediately after an equation, say in plain language:

  • what was substituted, eliminated, fitted, or solved;
  • what changed physically and what changed only mathematically; and
  • which symbol from the result is used next.

Prefer one complete equation chain over several paragraphs that describe the same algebra indirectly.

Use plain language

  • Use short sentences and concrete verbs: “set,” “partition,” “substitute,” “fit,” “solve,” and “compare.”
  • Use one name for one object. Do not introduce a synonym unless another field’s convention must be mapped explicitly.
  • Define unavoidable jargon the first time it appears.
  • Use a table for exact mappings or repeated comparisons. Use a diagram only when it makes a real dependency or branch easier to see.
  • Do not repeat the same warning in several sections. State it once where the mistake could first occur.

Keep the main text and supporting detail in different places

Content Placement
Main physical route and equations used downstream Main text
Required assumption or failure that changes the result Visible warning or important callout
Provenance, alternative convention, longer algebra, or implementation note Collapsed callout or precise link
Review state, artifact path, replay command, and implementation entrypoint Collapsed Review Links section

General Knowledge pages own reusable definitions and procedures. Worked examples follow those procedures with one concrete system. A worked example may choose a topology or approximation, but it must not silently redefine the general rule.

Review checklist

  • Can a new reader state the page’s purpose after the first screen?
  • Does the main-text structure match its Procedure, Concept, Method, Worked Example, or Design Target role?
  • Does every step consume a previously defined input and produce the next one?
  • Is each symbol defined once in LaTeX, with prose reserved for physical meaning?
  • Is every matrix tied to an explicit coordinate ordering and basis?
  • Are physical assumptions visibly distinct from mathematical operations?
  • Are units, conventions, observable, residual, and provenance stated where they matter?
  • Has unused detail been deleted, linked, or moved into a collapsed callout?
  • Does the page avoid duplicating a definition owned by another node?
  • Are prerequisite, just-in-time, and audit links placed at the correct strength?

This is the working v1 style. Human review may simplify it further; automation must not use it to mark a page Reviewed.

Source support and citation categories

Place a native citation beside the supported statement, assumption, or equation group. Give a useful section, equation, or page locator when it is actually known. A bibliography entry establishes source identity; it does not support every extension made on a page.

Use ordinary prose or a native callout to identify the contribution:

A short quote must preserve the original words and identify their location. Do not use quotation marks around a paraphrase. The following is a syntax schematic, not an actual quotation:

> Exact short quoted words. [@source-key, p. 12]

State which principles or model the explanation reorganizes. Put sources near the claims, not only at the end. The order and teaching language are ours; do not pretend to quote the author.

Reorganized explanation: the conservative circuit construction starts
from declared branch energies and independent flux coordinates [@vool2017].

Identify the starting definitions, source model, approximations, and algebra. A citation to the starting model is not attribution for our complete extension.

This-page derivation: using the stated linear boundary model [@gardiner1985],
we eliminate the declared internal variables below. The specialized elimination
is shown here; it is not quoted from that source.

Name the chosen convention, layout, method use, or proposed scope and its status. Source motivation does not make a choice universal or accepted.

Engineering choice: use the declared phasor convention consistently.
A source using the conjugate convention must be translated at the boundary.

The first and third snippets are illustrative authoring syntax, not evidence for a calculation. Substitute only actual source keys and known locators. Native Quarto citations resolve through the shared bibliography; do not add custom badges or a second citation registry to make unsupported material look supported.

Reference entry contract

References keeps source identity and support scope, not a second copy of the derivation. Each source note retains:

  • its bibliographic identity and DOI, arXiv version, or other primary location;
  • the exact concepts, claims, parameter families, or source-device examples it supports;
  • the assumptions, limits, process mismatch, and nontransferability conditions;
  • its relationship to the associated Knowledge concepts;
  • the actual review state and any source-identity or locator gap.

Core, supporting, and watchlist describe relevance, not scientific acceptance. A watchlist item is not an active model input. Keep unknown identities and unverified numerical claims explicit rather than manufacturing a citation. Keep source-device numbers distinct from a later project’s targets.

Ownership and review state

Surface Owner responsibility
Root Knowledge Cross-package/project reasoning, assumptions, literature connections, and evidence expectations.
Package resources Public model definitions, APIs, usage, validation, and result semantics for the selected version.
Consumer project Private bindings, study requests, execution, accepted targets, and retained evidence.
Notebook Its canonical source, generated pairing where applicable, and authorized execution/output retention.
References Source identity, support range, qualified examples, and limitations linked to the concepts that use them.
History Immutable or explicitly historical decisions and evidence, separate from current authority.

Link to the exact owning resource. A useful root concept link does not replace a selected package’s resources, and a package implementation is not a proof of a cross-package physical claim. The canonical node identifier is its root path; the corresponding public reading route is available only when that node is actually published. Private source links do not substitute for reader access.

Status Meaning
Seed Useful structure whose stated scope is not yet strongly supported.
Source-backed Relevant claims have primary or authoritative support at their actual scope.
Artifact-backed Inspectable evidence supports the stated claim, not every neighboring claim.
Reviewed Human review has accepted the stated semantics/readability/presentation scope.

Moving or rebuilding a page does not promote its review state. Automation checks links, citations, and metadata; it cannot grant Human review.

Migration and historical evidence

Move reusable explanation to its canonical owner and replace the duplicate current explanation with a precise link. Keep package operations with their version. Record old paths and incoming anchors so current consumers can update their links. Immutable receipts, saved results, frozen documentation versions, and historical source attribution remain unchanged.

The History page describes historical record placement; private artifacts stay with their source owners. A failed calculation or build is a technical observation, not permission to invent a new scientific acceptance threshold.