jeffryandClaude Opus 5
cc95488726
loom-cli's builder measured all three things we had published and none could be fetched by somebody who is not us: settled 404, .loom fetchable but not where a reader lands, and homelab-cluster 404 while this page named it as the canonical answer. Three for three. A public page naming a private thing as its canonical answer is worse than no example — it costs the reader a request and their confidence in the rest of the page. The page now says the example exists, is private, and why, and does not link it. The diagnosis is theirs and worth keeping: publication was being treated as a change of directory rather than the act publication.md describes. Moving a file into published/ is not publishing; the file becoming fetchable is. And reachable, the command we nearly cut for being a third kind of thing, found all three on the day it would have shipped. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
73 lines
2.7 KiB
Markdown
73 lines
2.7 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
|
|
|
|
**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.
|