b85bb27a9b
The doc previously conflated functions (transformations the device performs) with characteristics (measurable attributes). Surfacing Functions as their own ontology layer makes HOW names — which pack a function reference plus an attribute — readable without function definitions staying implicit. - new GLOSSARY.md at root: 5-layer ontology stack (WHAT / Function / Characteristic / Metric+Unit / Target), peer to CONTEXT.md (device-specific vocabulary) - qfd.md §2 opens with a Functions inventory (Type, Save, Publish, Recover, Boot, Provision); Render and Reconnect noted as sub-functions; Provision flagged as build-time-only in v0.1 - H1 "Keypress → glyph latency" → "Type latency (keypress → glyph)" - H4 "Cold boot → cursor ready" → "Boot latency (cold)" (the arrow transformation moves to the Functions inventory; the parenthetical keeps the residual qualifier) - cascade through §3 priority list, §6 critical-performance-budget rows for H1/H4, §8 inconsistencies, and quality-house.md TikZ column labels Matrix cell strengths held; no Σ recompute.
3.3 KiB
Glossary
Methodology vocabulary for this project's design docs. Device-specific
vocabulary (Save, Publish, Recover, Tracked, Local, …) lives in
CONTEXT.md.
Ontology stack
Five layers, top to bottom:
-
WHAT — user-facing requirement; an outcome the user values. Lives in
docs/qfd.md§1. Phrased as a sentence. Example: "Sub-second visible response to typing". -
Function — a transformation the device performs (verb, input → output). Lives in
docs/qfd.md§2's Functions inventory. Examples: Type, Save, Publish, Recover, Boot, Provision. -
Characteristic ≡ HOW — a measurable attribute of a function (or of an artifact or process). Noun. Lives in
docs/qfd.md§2's HOW table. Examples: latency, reliability, durability, binary size, build time. -
Metric + Unit — the quantity and scale used to express a characteristic's value. Examples: success rate (%), latency in seconds, size in MB. Packed into the target columns of §2; not given their own row.
-
Target — the value we aim for. The v0.1 / v1.0 columns of §2's HOW table. Examples: ≥ 95 %, ≤ 200 ms, ≤ 2 MB.
Side layers
- Component — subsystem that delivers one or more
characteristics. Lives in
docs/qfd.md§5. - ADR — Architecture Decision Record (
docs/adr.md). Captures a decision about a Component or Function with consequences. - Spike — time-boxed validation experiment that returns numbers
before integration. Referenced from
docs/qfd.md§6's "Watched on" column.
How the layers connect
WHAT → Function → Characteristic → Metric+Unit → Target
↑
Component → ADR
↑
Spike
A user's WHAT is delivered by one or more device Functions; each Function is sized by one or more Characteristics; each Characteristic is quantified by a Metric + Unit judged against a Target; each Characteristic is produced by one or more Components, whose choices are recorded in ADRs and validated by Spikes.
Anti-patterns
Recurring drifts the docs have had to clean up. Worth naming so we catch them early next time.
-
Solution-shape inside a WHAT or Characteristic name. Naming a specific solution (
Wi-Fi,Ctrl-G,commit,BOM,monospace,e-ink) inside an outcome or attribute. WHATs and Characteristics describe outcomes and attributes, not the technology that implements them. Move solution names to §7 tradeoffs or the relevant ADR. (Seedocs/qfd.md§8: W13 reframe, WHAT sweep, H6/H7/H8/H12 sweep.) -
Measure-vs-attribute drift. Naming a metric (
success rate,MTBF) where an attribute (reliability) would be cleaner. The metric belongs in the target column; the attribute belongs in the Characteristic name. -
Function-vs-characteristic conflation. Calling HOWs "engineering functions". A function is a transformation; a characteristic is one of its measurable attributes. HOWs measure functions; they are not functions. (See
docs/qfd.md§8 for the rename cascade.)