|
|
|
|
@ -0,0 +1,136 @@
|
|
|
|
|
---
|
|
|
|
|
title: Documentation Authoring Rules
|
|
|
|
|
type: guide
|
|
|
|
|
audience: human + agent
|
|
|
|
|
authority: canonical — how docs in this corpus are written and edited
|
|
|
|
|
status: current
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Documentation Authoring Rules
|
|
|
|
|
|
|
|
|
|
How to create and edit documentation in this repo. These rules exist because the
|
|
|
|
|
corpus is meant to read as a coherent, drift-free reference (and a future book) —
|
|
|
|
|
not as an accreting pile of notes. Read [`docs/README.md`](./README.md) first for
|
|
|
|
|
the map; this file is the *how-to-write* layer.
|
|
|
|
|
|
|
|
|
|
The rules are not aesthetic. Each one fixes a failure that actually happened
|
|
|
|
|
during the corpus migration.
|
|
|
|
|
|
|
|
|
|
## 1. Link the canon — never copy it
|
|
|
|
|
|
|
|
|
|
**The one law.** If you need to state a family, an intent, a verb, a size, a
|
|
|
|
|
color role, or any other canonical value, **link the canon** — do not paste a
|
|
|
|
|
copy.
|
|
|
|
|
|
|
|
|
|
- Semantic vocabulary → link [`CANON.md`](./CANON.md).
|
|
|
|
|
- Token scope / color model → link [`eidos/TSC.md`](../src/uix/eidos/TSC.md) and `THEMING.md §25`.
|
|
|
|
|
- A second copy is a future drift. This is literal: "7 families" survived in
|
|
|
|
|
three docs for weeks after the canon moved to 8, because each doc had
|
|
|
|
|
re-transcribed the list instead of linking it.
|
|
|
|
|
|
|
|
|
|
The doctrine fixes the *doctrine*; the code fixes the *numbers*. When a value
|
|
|
|
|
lives in code (per-family holds, channel signatures, full verb lists), **link
|
|
|
|
|
the `file:symbol`**, don't snapshot it into prose.
|
|
|
|
|
|
|
|
|
|
## 2. Every doc belongs to one stratum
|
|
|
|
|
|
|
|
|
|
Decide the stratum before you write; it decides where the file goes and how
|
|
|
|
|
timeless it must read.
|
|
|
|
|
|
|
|
|
|
| Stratum | Kind of doc | Lives in |
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
| **E0 — orientation** | entry point, glossary | `docs/README.md`, `docs/glossary.md` |
|
|
|
|
|
| **E1 — architecture** | how the layers fit | `src/uix/active_architecture.md`, per-layer `README.md` (in-place) |
|
|
|
|
|
| **E2 — canon** | fixed vocabulary / contracts | `docs/CANON.md`, `eidos/TSC.md` |
|
|
|
|
|
| **E3 — decisions / RFC** | why a thing is built this way | `docs/decisions.md` + the RFC / design files |
|
|
|
|
|
| **E4 — guides** | how to do a thing | `soma/COMPONENT_GUIDE.md`, `eidos/THEMING_GUIDE.md` |
|
|
|
|
|
| **E5 — module reference** | per-artifact docs | `src/arts/{name}/README.md` (in-place) |
|
|
|
|
|
| **process** | hand-offs, snapshots, audits | `docs/process/` — ephemeral, never a source of truth |
|
|
|
|
|
|
|
|
|
|
Layer and module reference stay **in-place** next to the code. Cross-cutting
|
|
|
|
|
orientation, canon, decisions and process live under `docs/`.
|
|
|
|
|
|
|
|
|
|
## 3. Reference docs are timeless
|
|
|
|
|
|
|
|
|
|
E0–E5 docs must read as if written today, forever.
|
|
|
|
|
|
|
|
|
|
- **No session hand-offs inside a reference doc.** "Handoff 2026-05-14",
|
|
|
|
|
"Correcciones del engine (2026-06-01)", "Estado actual" blocks belong in
|
|
|
|
|
`docs/process/`, not at the top of a README. Extract them.
|
|
|
|
|
- **No fragile numbers or dates in prose.** "66 components", "as of 2026-05-15"
|
|
|
|
|
rot. Convert relative dates to absolute, and prefer pointing at the live
|
|
|
|
|
source over stamping a count.
|
|
|
|
|
- **Don't hardcode catalogs.** A list of "implemented components" drifts the day
|
|
|
|
|
the next one ships. Point at the directory tree / the morfos / the registry
|
|
|
|
|
instead.
|
|
|
|
|
|
|
|
|
|
## 4. One source per concern
|
|
|
|
|
|
|
|
|
|
If two docs would say the same thing, one **owns** it and the other **links** it.
|
|
|
|
|
|
|
|
|
|
- Don't duplicate content across docs (the transcription chain, the layer split,
|
|
|
|
|
"what soma is not" lived in 4+ places). Pick the canonical home; everywhere
|
|
|
|
|
else links it.
|
|
|
|
|
- Two docs about the same subject must have **distinct roles**, stated in their
|
|
|
|
|
headers. Examples that shipped: `soma/README` (onboarding) vs
|
|
|
|
|
`SOMA_ARCHITECTURE` (deep reference); `COMPONENT_GUIDE` (build steps) vs
|
|
|
|
|
`COMPONENT_COMPLETION_CHECKLIST` (machine-audited acceptance).
|
|
|
|
|
- Never write a doc whose only content is re-exporting/redirecting another —
|
|
|
|
|
merge it, or make it a one-line pointer with a clear reason.
|
|
|
|
|
|
|
|
|
|
## 5. Frontmatter
|
|
|
|
|
|
|
|
|
|
Canon, index and reference docs open with YAML frontmatter:
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
---
|
|
|
|
|
title: <Doc title>
|
|
|
|
|
type: canon | index | guide | reference | notes
|
|
|
|
|
audience: human + agent
|
|
|
|
|
authority: <one line: what makes this authoritative or navigational>
|
|
|
|
|
status: current
|
|
|
|
|
# optional:
|
|
|
|
|
source: <where the content was extracted from>
|
|
|
|
|
related: { ... }
|
|
|
|
|
---
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Match the shape of [`CANON.md`](./CANON.md) / [`decisions.md`](./decisions.md).
|
|
|
|
|
|
|
|
|
|
## 6. Editing rules
|
|
|
|
|
|
|
|
|
|
- **Sections cited by number are load-bearing.** If a doc's `§N` is referenced
|
|
|
|
|
elsewhere in the corpus or in code comments, **do not renumber it**. To split
|
|
|
|
|
or shrink such a doc, use the **stub pattern**: leave a numbered pointer-stub
|
|
|
|
|
in the slot and move the content out (see THEMING → `TSC.md` / `THEMING_GUIDE.md`
|
|
|
|
|
/ `THEMING_NOTES.md`). Renumbering means sweeping every citation in the same
|
|
|
|
|
pass — only do that deliberately.
|
|
|
|
|
- **Fix links when you move content, and verify they resolve.** A wrong relative
|
|
|
|
|
path is silent (`soma/layers/GESTURES.md` vs the real `layers/gesture/GESTURES.md`).
|
|
|
|
|
- **Surgical.** Touch only what the task needs. Don't "improve" adjacent docs in
|
|
|
|
|
the same edit.
|
|
|
|
|
|
|
|
|
|
## 7. Language
|
|
|
|
|
|
|
|
|
|
- Target language is **English** (the migration is gradual; some layer docs are
|
|
|
|
|
still Spanish). When editing an existing doc, match its language — don't mix
|
|
|
|
|
two languages inside one doc.
|
|
|
|
|
- **Code comments are always English** (project-wide rule), including comments
|
|
|
|
|
inside fenced code blocks in docs.
|
|
|
|
|
|
|
|
|
|
## 8. Naming
|
|
|
|
|
|
|
|
|
|
- New decision/RFC/design docs: `rfc-{topic}.md` / `design-{subsystem}.md`
|
|
|
|
|
(kebab). The legacy `*_ENGINE_RFC.md` / `DESIGN_*.md` names are kept only
|
|
|
|
|
because they are cited as provenance across the code; don't add more in the
|
|
|
|
|
old shape.
|
|
|
|
|
- Markdown links, relative paths.
|
|
|
|
|
|
|
|
|
|
## Before you commit a doc
|
|
|
|
|
|
|
|
|
|
- [ ] Stratum chosen; file in the right place (in-place vs `docs/`).
|
|
|
|
|
- [ ] No canonical value copied — linked instead.
|
|
|
|
|
- [ ] No hand-off / dated-status / hardcoded catalog in a reference doc.
|
|
|
|
|
- [ ] Frontmatter present (for canon/index/reference).
|
|
|
|
|
- [ ] No `§N` renumbered that something cites; links verified to resolve.
|
|
|
|
|
- [ ] New doc wired into [`docs/README.md`](./README.md) if it's a top-level entry.
|
