From ffa56daa4120bab421a933f6d522ac72fb0a5b50 Mon Sep 17 00:00:00 2001 From: Jeff Gonzalez Date: Tue, 8 Sep 2026 08:58:17 -0400 Subject: [PATCH] publication says how; starting.md points at an example you can fetch 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) --- .loom/event-log.md | 36 ++++++++++++++++++++++++++++++++++ .loom/published/publication.md | 15 ++++++++++++++ .loom/published/starting.md | 15 ++++++++------ 3 files changed, 60 insertions(+), 6 deletions(-) diff --git a/.loom/event-log.md b/.loom/event-log.md index 45ef9a1..55cde4d 100644 --- a/.loom/event-log.md +++ b/.loom/event-log.md @@ -3676,3 +3676,39 @@ turns conversion from lossy-in-the-tree into lossy-absolutely.** by the document: *the gap file is the only mechanism here where somebody who cannot edit your document can still put a defect in front of you, and it caught what review by the author did not.* + +--- + +## 82 — publication says how, not only what + +**Decided.** `publication.md` gains a five-step procedure, with **fetch it, from +somewhere that is not your machine and not your account** as step 4, and the note +that steps 1 to 3 are things you do while step 4 is a fact about the world you +find out. + +**Advances:** the reachability property becomes something a reader can perform +rather than agree with. + +**Declined:** a separate procedural document. *`publishing.md` beside +`publication.md` is two files one letter apart about the same subject, and the +gap filed against this document was that it was underspecified — which is an +argument for filling it in, not for splitting it.* **Say it once, where it is +owned.** + +**The belief that could turn out false:** that a numbered list gets followed where +a stated property did not. *No evidence either way; the property was stated +yesterday and the three failures predate it.* + +## 83 — starting.md points at a public worked example + +**Decided.** The closing section of `starting.md` now links +`jeffry/homelab-cluster` instead of describing an example the reader cannot fetch. + +**Why it was wrong:** *the example went public four days ago and the page still +said it was private.* **The first document a newcomer reads was teaching the +lesson by being an instance of it**, which is not the same as teaching it. + +*The lesson is kept, because it was expensive, and now it is the reason the link +exists rather than the reason there is none.* **And the section says the thing the +split actually taught:** *the documents got better for being written to a stranger, +which was not why we did it.* diff --git a/.loom/published/publication.md b/.loom/published/publication.md index 385e26e..c0d9231 100644 --- a/.loom/published/publication.md +++ b/.loom/published/publication.md @@ -37,6 +37,21 @@ copy without inheriting the visibility it was published under.* **The test is a fetch you did not perform.** +## Doing it + +1. **Decide it is a contract and not a detail.** *This is the whole decision and + the rest is mechanics.* +2. **Move the file into `.loom/published/`.** *One commit, so the diff carries it.* +3. **Say who the readers are** — *if it is not obvious from where it landed.* +4. **Fetch it.** *From somewhere that is not your machine and not your account.* +5. **Record the decision**, if you keep a log. + +**Step 4 is the one that gets skipped and the only one that can fail.** *Steps 1 +to 3 are things you do; step 4 is a fact about the world that you find out.* + +*Then say what it depends on. A published document that quietly requires a private +one has moved the problem rather than solved it.* + ## What is published is a document **Prose, in whatever form its readers need.** *If a repository organises its diff --git a/.loom/published/starting.md b/.loom/published/starting.md index 7d997a3..b9eefba 100644 --- a/.loom/published/starting.md +++ b/.loom/published/starting.md @@ -60,13 +60,16 @@ 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.** +**[`jeffry/homelab-cluster`](https://git.hypertheory-labs.dev/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 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.** +**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.