From f026f3ea55387755fec85b3570ea3e4b2207293d Mon Sep 17 00:00:00 2001 From: Jeff Gonzalez Date: Mon, 7 Sep 2026 11:27:19 -0400 Subject: [PATCH] a starting page, and it points at the example rather than replacing it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .loom/published/starting.md | 68 +++++++++++++++++++++++++++++++++++++ README.md | 5 ++- 2 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 .loom/published/starting.md diff --git a/.loom/published/starting.md b/.loom/published/starting.md new file mode 100644 index 0000000..e5fba07 --- /dev/null +++ b/.loom/published/starting.md @@ -0,0 +1,68 @@ +# 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. diff --git a/README.md b/README.md index fd034dc..516d0d4 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,11 @@ - [Recording decisions](.loom/published/recording-decisions.md) — what an entry says, and why it is never revised - [Publication](.loom/published/publication.md) — what `.loom/published/` means +- [Starting one of these in a repository](.loom/published/starting.md) — the one + page here that tells you what to do, because a set of primitives with no + starting point is a puzzle -**Nothing here says what to *do*.** *`loom/annotating`, `loom/cart` and +**Nothing else here says what to *do*.** *`loom/annotating`, `loom/cart` and `loom/externals` are built on these and are where the practices live.* **Most repositories will never read this.** *Its audience is people building