jeffryandClaude Opus 5
ffa56daa41
publication.md gains the procedure, with "fetch it, from somewhere that is not your machine and not your account" as its own step. Steps 1-3 are things you do; step 4 is a fact about the world you find out, which is why it is the one that gets skipped. Declined a separate procedural document: publishing.md beside publication.md is two files one letter apart, and the gap filed was that this document was underspecified. starting.md still described the worked example as private and refused to link it. It went public four days ago. The first page a newcomer reads was demonstrating its own lesson instead of teaching it. Entries 82-83. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.0 KiB
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.
.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 —
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.