# 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

**There is a worked example — six documents, one gap, no decomposition — and it
is private.**

*It describes a cluster in enough detail to be a target list, so it is not
published, and **this page will not link you to something you cannot fetch.***
**If you have access, ask for it by name; if you do not, the two questions at the
top are the whole of 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.