# Starting one of these in a repository

**Make a `.loom/` directory. Everything else follows from two questions.**

---

## What can a reader not already know?

**That is what you publish**, in `.loom/published/`, as ordinary documents.

**Not what your service does** — its code says that. **Not how Kubernetes or
Kafka or React work** — that is somebody else's documentation, and a copy of it
here goes stale silently while reading as though it were true.

> **Write the delta.** *"The default ingress class publishes to the internet, so
> omitting it is how you leak something."* **Nobody could have guessed that, and
> nothing else here will tell them.**

**A good page ends with how to check it is still true**, and a date. *Nothing
serves the truth about a running system, so the only mechanism is somebody
looking.*

## What do you need that nothing provides?

**That is a gap**, in `.loom/gaps/`.

**The test: could you say whose job it is?** *If yes, it is a claim against them
and belongs with them. If no, it is a gap.*

**Record what you are doing instead** — *"we are using Docker Hub for now."*
**Forgetting it was provisional is the disease; the provisional answer is fine.**

---

## Then, only if you have something to say

**`.loom/externals/`** — a copy of somebody's document you depend on, with what
you use and what you expected and did not find, beside it. See
[externals](https://git.hypertheory-labs.dev/loom/externals).

**`.loom/venues/`** — choices you made about something with no document to hang
them on. *Kafka, React, HTTP.*

**`.loom/event-log.md`** — decisions, if you are keeping them here.

> **A file that carries no delta should not exist.** *If you do exactly what
> somebody else's document says, write nothing — recording the adoption is
> ceremony.*

## Write a `.loom/README.md`

**Say what is in `published/` and why somebody would want it.** *Link the
documents. One line for the curious about what `.loom` is.*

**Nobody should need to understand any of this to use it** — *they are documents
in a folder, and a reader who ignores the vocabulary entirely should still get
what they came for.*

---

## Look at one instead of reading this

**[`jeffry/homelab-cluster`](https://git.hypertheory-labs.dev/jeffry/homelab-cluster)** —
*six documents, one gap, no decomposition.* **It describes what a home cluster
offers to somebody deciding whether to put something on it**, and a reader who
has never heard of any of this still gets what they came for.

**It was private, and being unable to link to it is what made the split obvious.**
*The operational tree is a version inventory and a target list; the pages telling
somebody what to decide are neither.* **So the manifests moved to a private
sibling and the documents stayed** — *and the documents got better for being
written to a stranger, which was not the reason for doing it.*

> **A public page naming a private thing as its canonical answer is worse than no
> example**, and this page did exactly that until somebody measured it.