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.