diff --git a/.loom/externals/.locks b/.loom/externals/.locks index 3adf4cf..9ecd3f5 100644 --- a/.loom/externals/.locks +++ b/.loom/externals/.locks @@ -4,9 +4,9 @@ git.hypertheory-labs.dev/jeffry/homelab-cluster/gitea.md https://git.hypertheory-labs.dev/jeffry/homelab-cluster/raw/branch/main/.loom/published/gitea.md "530c5bef62bbd325956ed170bb2decf37975e4b9" git.hypertheory-labs.dev/loom/annotating/annotating.md https://git.hypertheory-labs.dev/loom/annotating/raw/branch/main/.loom/published/annotating.md "9b1f7e6ca92f2339b2d433686c27845362944bdb" git.hypertheory-labs.dev/loom/bedrock/loom-directory.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/loom-directory.md "ee0f49cb900c0812678061971194325d9cba366a" -git.hypertheory-labs.dev/loom/bedrock/publication.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/publication.md "385e26ef4108029c12a4267600399da1eece52af" +git.hypertheory-labs.dev/loom/bedrock/publication.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/publication.md "c0d9231aa8eed3041c60b72da5735585457fbc90" git.hypertheory-labs.dev/loom/bedrock/recording-decisions.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/recording-decisions.md "d190eeae7929b9a99ecf09211d94e7e5b32635bd" git.hypertheory-labs.dev/loom/bedrock/sibling-facets.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/sibling-facets.md "a46446a34ccb8bfc533d3cce19f4c88548c4fa04" -git.hypertheory-labs.dev/loom/bedrock/starting.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/starting.md "7d997a30248a88c90b23f2f9453d7cfceb03848e" +git.hypertheory-labs.dev/loom/bedrock/starting.md https://git.hypertheory-labs.dev/loom/bedrock/raw/branch/main/.loom/published/starting.md "b9eefba0f4668a496ccfc6a1377277f0721456d2" git.hypertheory-labs.dev/loom/cart/cart.md https://git.hypertheory-labs.dev/loom/cart/raw/branch/main/.loom/published/cart.md "15331f1a9cc81bf61a44830cfbb7c274f4c2b119" git.hypertheory-labs.dev/loom/externals/externals.md https://git.hypertheory-labs.dev/loom/externals/raw/branch/main/.loom/published/externals.md "a7586eb52caf275d9bcedbbd8042c43e5aaad0b9" diff --git a/.loom/externals/git.hypertheory-labs.dev/loom/bedrock/publication.md b/.loom/externals/git.hypertheory-labs.dev/loom/bedrock/publication.md index 385e26e..c0d9231 100644 --- a/.loom/externals/git.hypertheory-labs.dev/loom/bedrock/publication.md +++ b/.loom/externals/git.hypertheory-labs.dev/loom/bedrock/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/externals/git.hypertheory-labs.dev/loom/bedrock/starting.md b/.loom/externals/git.hypertheory-labs.dev/loom/bedrock/starting.md index 7d997a3..b9eefba 100644 --- a/.loom/externals/git.hypertheory-labs.dev/loom/bedrock/starting.md +++ b/.loom/externals/git.hypertheory-labs.dev/loom/bedrock/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.