docs(qfd): introduce Functions layer and GLOSSARY.md ontology

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.
This commit is contained in:
Julien Calixte
2026-05-19 14:45:12 +02:00
parent 8a223e7837
commit b85bb27a9b
3 changed files with 215 additions and 64 deletions

82
GLOSSARY.md Normal file
View File

@@ -0,0 +1,82 @@
# Glossary
Methodology vocabulary for this project's design docs. Device-specific
vocabulary (Save, Publish, Recover, Tracked, Local, …) lives in
[`CONTEXT.md`](CONTEXT.md).
## Ontology stack
Five layers, top to bottom:
1. **WHAT** — user-facing requirement; an outcome the user values.
Lives in [`docs/qfd.md`](docs/qfd.md) §1. Phrased as a sentence.
Example: "Sub-second visible response to typing".
2. **Function** — a transformation the device performs (verb,
input → output). Lives in [`docs/qfd.md`](docs/qfd.md) §2's
Functions inventory. Examples: Type, Save, Publish, Recover,
Boot, Provision.
3. **Characteristic****HOW** — a measurable attribute of a
function (or of an artifact or process). Noun. Lives in
[`docs/qfd.md`](docs/qfd.md) §2's HOW table. Examples: latency,
reliability, durability, binary size, build time.
4. **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.
5. **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`](docs/qfd.md) §5.
- **ADR** — Architecture Decision Record ([`docs/adr.md`](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`](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.
(See [`docs/qfd.md`](docs/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`](docs/qfd.md) §8 for the rename cascade.)