jeffryandClaude Opus 5
f026f3ea55
Someone in an empty repository saying "set this up" has nothing to read. The four primitives say what things are and deliberately not what to do, which leaves a set of primitives with no starting point — a puzzle rather than a foundation. Two questions carry it: what can a reader not already know, which is what you publish; and what do you need that nothing provides, which is a gap. Everything else is conditional on having something to say, and the page says plainly that a file carrying no delta should not exist. It ends by pointing at jeffry/homelab-cluster and saying that if the two disagree, the example is right. Precedent beats description, and a page about writing documents should not be the longest document. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# 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, and a `README` that says what the
|
|
root documents are for and what these are for.*
|
|
|
|
**It is a better answer than this page**, and if the two ever disagree, it is
|
|
right.
|