Writing the Docs: 2026 Edition  🔗 **Source:** [Writing the Docs: 2026 Edition](https://wrla.ch/log/2026/08/writing-the-docs-2026-edition/) > [!note]+ Document Notes > tags: [documentation-architecture, diataxis, agent-skills, design-docs, ground-truth-docs, decision-records, llm-workflow] > author: William Lachance (wlach) - inferred, see Attribution > source: https://wrla.ch/log/2026/08/writing-the-docs-2026-edition/ > reference: "Writing the Docs: 2026 Edition" - wrla.ch, August 2026 > date created: 2026-08-26 13:05 > > > [!info] Generated analysis - not the author's words. Sections below are machine-written > > from the captured source. Only text inside `> [!quote]` blocks is verbatim from the author. > > Do not quote or attribute any other line to the named author. > > # Title: Writing the Docs: 2026 Edition > > **Attribution - inferred, and here's the basis.** Reader's `author` field reads `wrla.ch`, a domain. **The author is William Lachance**, who blogs at wrla.ch and posts as `wlach`. Two things in the text establish this: he links to `github.com/mozilla/data-docs/commits?author=wlach` as *his own* commit history, and he claims authorship of three named Mozilla posts (the docs.telemetry.mozilla.org reorganization, "Mozilla Telemetry in 2020," and "The Glean Dictionary"). **This is a reviewer inference from in-text evidence, not a stated byline.** He states he worked on documentation and metadata at Mozilla Data and left in **January 2022**. > > **Register.** A practitioner retrospective - five-year revisit of four documentation principles, re-examined against LLMs. Personal blog, no vendor interest, no product to sell except two open-source tools of his own that he explicitly declines to over-claim for. > > **Why it matters here.** This is the **highest-value source in this batch for Courtney's actual tooling**, and one item is unusually well-timed: it supplies a concrete fix for a problem measured in this very session - 159 skills, ~11,709 tokens of always-on descriptions, and 30 skill bodies over 8KB with nowhere to push detail. Lachance's skill-as-pointer pattern is that fix, in four lines. > <!-- deep-read:sections start --> ## Table of Contents 1. Summary 2. Main Content and Notes 3. References 4. Paraphrase 5. Newsletter 6. Action Items 7. Hypotheses 8. Methodology 9. Questions 10. Future Research 11. Implications 12. Learning Styles Assessment 13. Accessibility Assessment 14. DEIB Assessment 15. Logical Validity 16. DARVO Analysis 17. Conclusion 18. Refactor Appendix 19. Template Library ## References (in-page) - **Diataxis** - the four-category documentation framework he now treats as canonical. (Divio's system is noted as a precursor by the same author.) - **Design Docs at Google** (c. 2015) and **Joel Spolsky, "Painless Functional Specifications"** (2000) - the proposal-culture lineage. - His own Mozilla writing: **A principled reorganization of docs.telemetry.mozilla.org** (May 2020) - **Mozilla Telemetry in 2020: From "Just Firefox" to a "Galaxy of Data"** (July 2020) - **The Glean Dictionary** (January 2021). - **Sphinx autodoc** and **doxygen** - the prior art for derive-from-source reference docs. - **repo-parser** and **idr-tools** - his two current projects. - **probe-scraper**, **mozilla-schema-generator**, **Google Data Catalog**, **alembic** and **goose** (the filename-convention source). ## Summary **The setup.** Five years after leaving heavy documentation work at Mozilla Data, Lachance revisits four principles - separate the what from the how - reference documentation should derive from ground truth - document your decisions and process - continuous improvement - and asks what LLMs changed. His framing of why any of it matters: > *"Fundamentally, it's an act of care both to yourself and your peers, past and present."* **Principle 1 - separate the what from the how.** He credits **Diataxis** (tutorials - explanation - how-to - reference), noting he'd independently arrived at its principles before knowing it existed. **Verdict on LLM impact: no change** - and for tutorials and explanations, *more* need than before: > *"as we delegate more of the day-to-day work to machines and reduce the amount of hands-on work which generates understanding, our need for these aids has only increased."* He adds the point about tutorials most people get wrong: they *"were actually never really meant to describe how to do something"* - the purpose is hands-on experience and a feeling of success, so the reader gains confidence to go deeper. His one quibble with Diataxis is that complex topics sometimes need the categories mixed, and he cites a long sprawling explanation-plus-theory piece of his own that engineers repeatedly told him was the most useful thing they had. **The finding that matters most, and it's in the how-to section.** Agent Skills are *"at heart, just little markdown docs named SKILL.md which describe how to perform a particular task"* - and therefore **complementary to how-to docs rather than a replacement.** Write the how-to for humans, then point a skill at it: ```markdown --- name: query-main-ping-telemetry-table description: Query the main ping telemetry table in Bigquery --- Refer to `docs/howtos/query-telemetry-table-in-bigquery.md` ``` With the reasoning: *"I'm often surprised at how quickly modern large language models can figure out how to do something essentially from first principles, but if you've arrived at a good solution already, why bother doing that? Just give them a cookbook and save the time and the tokens."* Plus the debuggability argument - when you need to check the work or do part of it yourself, *"the exact set of steps is right there."* **Principle 2 - reference docs derive from ground truth.** Past a few hundred entities, hand-written reference documentation stops working, and **generating it doesn't help**: > *"Even if you can generate a perfect first draft, you've only postponed the problem: the implementation will change, and independently maintained reference documentation will drift from it."* The fix is deriving reference docs from a machine-readable representation - source code, metrics definitions, schemas - **and linking back to it** so the reader can verify the claim. Old idea (Sphinx autodoc, doxygen), inconsistently applied. **And it's now a hallucination control:** *"Having a clear statement of the system-as-it-currently-is (with citations) is the best defense against that."* He also defends building a custom site over adopting a generic data-catalog SaaS, on a domain-mismatch argument: *"unless your product is a database, the domain of a generic data catalog (schemas, tables) is going to be inherently different than that of your business."* Mapping your concepts onto a vendor's model is *"honestly 90% of the effort"* - so spend the remaining 10% on something that fits. His **repo-parser** formalizes the extraction step: a git repo plus rules produces a duckdb database or in-memory representation. He explicitly declines to claim it's the right abstraction - *"Time will tell."* **Principle 3 - proposals and decision records, and the strongest idea in the piece.** On LLM impact he gives two answers: **"almost not at all" and "totally."** *Almost not at all* for traditional human-alignment proposals. A model can draft, but *"to be maximally effective both the initial communication and response should be the product of human interaction."* He also names the precondition most organisations miss: *"having an effective proposal requires a strong commitment to psychological safety."* *Totally* for day-to-day work where a model writes the implementation. Since he was already encoding intent, goals, and constraints into prompts: > *"Since I found that I was encoding these details in a prompt, I thought: hey, why not just make the prompt a design doc?"* A human writes intent, goals, non-goals, and a solution sketch in markdown; the model collaborates on detailed design; then implementation proceeds. **The document is checked in alongside the code** and can be reviewed in a PR like any other artifact. His stated contrast with plan mode: *"a fairly deliberate structure (explicit dating and proposal template) and a higher level of human involvement in the earlier stages of design."* Filenames borrow from database migration tools (alembic, goose) - `202601180308-upload-packages-to-pypi.md` - because these records are *"moments in time."* Tooling lives in **idr-tools**. The problem it solves is stated bluntly: models *"have the memory of a goldfish,"* AGENTS.md *"can only tell it so much,"* and even with long context *"important facts can be missed or given too little weight."* **Principle 4 - always be improving.** Typos, bitrotted instructions, small clarity fixes, continuously. An LLM can do this with human review, and either way the result is *"an (infectious) demonstration of actual care"* that eventually fades into *"the way we do things around here."* **Conclusion.** The principles hold, in some cases more strongly: *"So long as there are complex systems, I don't think describing them in forms that are meant to explain will go out of style."* ## Main Content ### Notes **Framing and provenance.** - Roughly five years since he worked heavily on documentation and metadata at **Mozilla Data**; left Mozilla **January 2022** and hasn't followed closely since. - Deliberately uses Mozilla examples because they're on the public record and he can discuss them freely. - Background work he never wrote up explicitly: **"proposal culture"** and collaborative software design via design documentation. - The value claim: organizing information and making it legible *"leads to better workplaces and makes us generally more productive. Fundamentally, it's an act of care both to yourself and your peers, past and present."* - Four principles under review: separate the what from the how - reference documentation should derive from ground truth - document your decisions and process - continuous improvement. **1. Separate the what from the how.** - He was repeating **Diataxis** principles before knowing the framework existed; it's now his go-to *"because it's so well written and explained."* - The four categories as he states them: **Tutorials** (basic task step by step, for beginners) - **Explanation** (longer, the "why," for all) - **How-to** (a specific task, for non-beginners) - **Reference** (ground truth, the "what," for all). - Outcome at Mozilla: Diataxis was never fully applied, but emphasising tutorials and getting-started docs while pushing reference and deep dives later made the site more useful. Concrete signal - he could answer internal Slack questions by linking a step-by-step section. - **Quibble:** complex tasks sometimes need the types mixed. His "Visualizing Percentiles of a Main Ping Exponential Histogram" was *"a very long and sprawling mix of explanation with theory"* and he counts that as a strength; Firefox engineers repeatedly said it was extremely helpful. Evidence offered for durability: *"no one has felt motivated to take it down."* - **LLM impact: none.** *"Do LLMs change anything here? I would argue no."* **Tutorials and explanations.** - *"as we delegate more of the day-to-day work to machines and reduce the amount of hands-on work which generates understanding, our need for these aids has only increased."* - On using LLMs to draft this type of writing: *"it's interesting to see what they miss or get wrong: often some vital fact or nuance is not there, and they have a tendency to emphasize incidental details."* - **The commonly-missed point about tutorials:** they *"were actually never really meant to describe how to do something."* The purpose is hands-on experience and a feeling of success, building confidence for the advanced tasks where how-to and reference matter. - *"hands-on learning and action is still the best way for most people to learn anything, including how to work with computational systems."* **How-to documentation - "changed the most and the least."** - Historically his view: most human-written documentation should be how-to, because it's the most broadly useful and *"tended to age much better than explanation or reference material that would frequently go out of date."* - Now an LLM often executes these tasks. - **Agent Skills are how-to docs.** *"little markdown docs named SKILL.md which describe how to perform a particular task. I think they are entirely complementary to the approach."* - **The pattern:** write a detailed how-to, then create a thin skill that points at it. ```markdown --- name: query-main-ping-telemetry-table description: Query the main ping telemetry table in Bigquery --- Refer to `docs/howtos/query-telemetry-table-in-bigquery.md` ``` - *"An LLM can process a well-written markdown file just as easily as a human."* - **Why not let the model derive it:** *"I'm often surprised at how quickly modern large language models can figure out how to do something essentially from first principles, but if you've arrived at a good solution already, why bother doing that? Just give them a cookbook and save the time and the tokens."* - **Debuggability:** *"if you need to debug what it's doing (or do part of it yourself), the exact set of steps is right there."* **2. Reference documentation should derive from ground truth.** - Quoted from his own 2020 piece: with **N applications x M ping types**, the number of canonical tables grew past what hand-written documentation could cover. - *"if you're dealing with hundreds or thousands of entities (or more), a manual approach to writing the documentation just isn't going to work."* - **The key argument against generation:** *"Even if you can generate a perfect first draft, you've only postponed the problem: the implementation will change, and independently maintained reference documentation will drift from it."* - The solution: derive from a **machine-readable representation** - source code, metrics definitions, dataset definitions - and **link back to the original source** so assertions can be verified. The Glean Dictionary linked to the schema or artifact that generated each entry. - Prior art: **Sphinx autodoc**, **doxygen**. *"a pretty old idea... although it hasn't been super consistently applied in modern data engineering from 2020 to 2022 or so."* - Cultural observation: *"we tend to emphasize getting to an answer ('How many users did XYZ?') over how the answer was derived."* Mozilla was an exception, with engineers who cared about derivation. - **Ground truth as hallucination control:** conclusions from inaccurate source data compound, *"leading to yet more confusion and problems that only get caught at review time (if you're lucky)."* A cited statement of the system-as-it-is *"is the best defense against that"* - it reduces hallucination **and** gives a human operator something to check against. **Custom tooling versus SaaS catalogs.** - At the time he evaluated **Google Data Catalog** and found it solved only part of the problem: a view on BigQuery tables, not on *"the domain objects we care about (products, pings, measures, and tools)."* Mapping was possible but the interface was *"slow and clumsy and requires detailed knowledge of how these higher level concepts relate to BigQuery primitives."* - The general argument: *"unless your product is a database, the domain of a generic data catalog (schemas, tables) is going to be inherently different than that of your business."* True *"whether what you care about is the experience of Firefox users or dispatching taxi cabs."* - Forcing users to think in schema terms *"is to move them away from asking actual product questions."* - **The economic argument:** mapping your concepts onto a cross-industry product's model is *"honestly 90% of the effort, in my experience"* - so a little more effort on a custom interface may be *"the missing piece to make that work maximally impactful."* And *"even easier today thanks to large language models."* - **repo-parser** - his framework formalising ground-truth extraction. Given a git repo and rules (*"convert this set of markdown frontmatter into a set of tags"*), it turns a forest of markdown, YAML, and JSON into a duckdb database or in-memory representation, usable for a data catalog, a docs site, or other things. Its example site is built from a README at build time. - **Explicit hedge:** *"I'm not certain if repo-parser is exactly the right abstraction for building something like this, or if it's more like an architectural design pattern where every implementation is bespoke. Time will tell."* **3. Proposals and architectural decision records.** - *"Ground truth can tell us what, but doesn't say much about why."* - The design-doc practice: before a large piece of work, circulate a document with **problem statement, goals, non-goals, a preliminary solution, and alternatives considered**; discussion proceeds asynchronously in comments. - Questions proposals answer: *"Why this design? Why now? ... How does this impact security, reliability...? What comes next?"* - Two benefits: rejecting or modifying bad designs before effort is spent, and *"they allow us to distribute understanding of what is being built and why across teams."* He calls it *"one of the best ways I've found to align a diverse group of human beings around a single objective."* Footnote: he believes the same of code review. - Lineage: **Design Docs at Google** (~2015), **Painless Functional Specifications** (Spolsky, 2000), and *"I'm sure you can find articles about this all the back to the 70s."* - **The puzzle he poses:** *"many organizations struggle to have a good proposal culture. If the ideas are so obvious, why?"* - **His partial answer - psychological safety.** *"If people don't feel like their design or feedback is going to be taken in good faith, the proposal process won't work very well. People will be hesitant to put things out there and to engage, and the opportunity for learning will be reduced."* In a healthy workplace *"people are constantly being guided towards presenting their best ideas, with the knowledge that their colleagues are there to support them."* **LLM impact on proposals: "almost not at all" and "totally."** - **Traditional proposals - unchanged.** A model can help brainstorm and draft, but *"to be maximally effective both the initial communication and response should be the product of human interaction. That ensures that the proposal is an expression of a fully fleshed out train of thought and represents real effort."* - **Day-to-day LLM implementation - transformed.** - The problem: *"since they have the memory of a goldfish, I've found getting them to produce the right thing a bit of a crapshoot. Yes, there is AGENTS.md but that can only tell it so much: there's always more 'implicit' context that is needed to solve a problem of any complexity. And even with extremely long context, important facts can be missed or given too little weight."* - **The move:** *"Since I found that I was encoding these details in a prompt, I thought: hey, why not just make the prompt a design doc?"* - Workflow: human expresses intent, goals, non-goals, and a solution sketch in markdown -> collaborate with the LLM on detailed design -> proceed to implementation -> **check the document in alongside the code** as a guide to what was done. In a PR workflow it can be critiqued like any other artifact. - **Versus plan mode:** *"The key difference is a fairly deliberate structure (explicit dating and proposal template) and a higher level of human involvement in the earlier stages of design."* - **Filename convention** from database migration tools (alembic, goose), to encode chronology since these records are *"moments in time"*: `202601180308-upload-packages-to-pypi.md`. - **Template** (his worked example, PyPI upload automation): `## Overview` -> `### Problem Statement` -> `### Context (as needed)` -> `### Goals` -> `### Non-Goals` -> `### Proposed Solution`. - Tooling: **idr-tools**; samples there and in repo-parser's `idrs` subdirectory. **4. Always be improving.** - Typos, bitrotted instructions, small clarity improvements - *"over time this type of enhancement ensures that the documentation is maximally useful both to humans and machines."* - *"You can use an LLM to do this automatically, but obviously you want a human being to review the output."* - The result is better docs **and** *"an (infectious) demonstration of actual care. It's a way of supporting others, including your future self."* - *"After some time, repeated small actions become a habit, others follow along and it fades into the background as 'the way we do things around here'."* **Conclusion.** - He wouldn't write the original articles the same way today, but the conclusions hold *"in some cases even more strongly."* - *"So long as there are complex systems, I don't think describing them in forms that are meant to explain will go out of style. If anything, it becomes more powerful and needed at all stages of the design and build process."* ## References - **Diataxis** - the framework. Directly relevant: Courtney's `docs-reviewer` agent already reviews against it, so this is a source that validates existing tooling rather than proposing new. - **idr-tools** - the repository behind the dated-decision-record workflow. **The highest-value unread link here**, since the template and tooling are the actionable part. - **repo-parser** - ground-truth extraction from a git repo into duckdb or memory. Plausibly relevant to her vault, which is a forest of markdown with YAML frontmatter - exactly repo-parser's stated input. - **Design Docs at Google** (~2015) and **Painless Functional Specifications** (Spolsky, 2000) - the lineage, and useful for arguing that this is settled practice rather than novelty. - **Sphinx autodoc**, **doxygen** - prior art for derive-from-source reference documentation. - His three Mozilla posts, **probe-scraper**, **mozilla-schema-generator**, and the **Glean Dictionary** - the worked history behind the ground-truth argument. - **alembic** / **goose** - origin of the timestamp-prefix filename convention. ## Paraphrase **On the skill-as-pointer pattern, which is the most immediately useful thing in this batch.** Lachance's observation that a SKILL.md is just a how-to doc for a different reader has a consequence he states plainly and most people miss: **you don't have to write the content twice, and you shouldn't.** Write the how-to once, for humans, in the docs tree where it gets reviewed and maintained; make the skill a four-line pointer. The skill's always-loaded surface stays tiny, the body lives somewhere with a natural update path, and a human reading the docs and a model reading the skill are looking at the same text - so they can't drift. **Why that lands hard here specifically.** Earlier in this session I measured Courtney's skill library: **159 skills, roughly 11,709 tokens of always-on descriptions, and 30 bodies over 8KB with nowhere to push detail.** That last part was the diagnosis - progressive disclosure only works if there's somewhere below the SKILL.md to put things. Lachance's answer is that the somewhere already exists: it's the documentation. **This is a fix for a measured problem, arriving in the same week the measurement was taken.** **On "why bother doing that? Just give them a cookbook and save the time and the tokens."** The line is almost throwaway and it settles a real question. A capable model *can* derive a procedure from first principles, which tempts people into thinking written procedures are obsolete. His answer is economic rather than epistemic - derivation costs tokens and time and produces a different answer each run, whereas a cookbook is free, fast, and identical every time. And the debuggability point is the stronger half: **when the run goes wrong, a written procedure gives you something to diff the behaviour against.** Without it, you're debugging a black box against an unstated standard. **On the ground-truth argument, which is the sharpest thing in the piece.** *"Even if you can generate a perfect first draft, you've only postponed the problem."* This is the correct objection to LLM-generated reference documentation, and it isn't about quality - a perfect draft has the same defect as a mediocre one. **The defect is that a generated artifact is a snapshot with no relationship to its source.** Reference docs need a *derivation*, not a *creation*, and generation makes the drift problem invisible by producing something that looks maintained. The corollary he draws is the useful one: **cited ground truth is a hallucination control**, because it gives the human operator something to check against. **On the design-doc-as-prompt move.** *"Since I found that I was encoding these details in a prompt, I thought: hey, why not just make the prompt a design doc?"* The insight is that the information a proposal contains and the information a model needs are **the same information** - intent, goals, non-goals, constraints, a solution sketch - so writing it once in a durable format serves both. The three properties that make it better than a prompt: it's **dated**, so it reads as a moment in time rather than current truth; it's **structured**, so the non-goals section forces the thinking people skip; and it's **checked in**, so it can be reviewed in a PR and read later by whoever inherits the code. **On his distinction from plan mode, which is fair and worth being precise about.** He names two differences: deliberate structure with explicit dating, and more human involvement early. Both are real, and the one he doesn't name is arguably the biggest - **plan mode's artifact is ephemeral.** A plan approved in a session and then executed leaves nothing behind; his leaves a dated file next to the code. The tradeoff is friction, and he doesn't pretend otherwise. **On psychological safety as an infrastructure question.** He asks why proposal culture fails in organisations where the ideas are obvious, and answers that it requires *"a strong commitment to psychological safety."* This is the same shape as a finding that recurred four times in this week's reading: **a process is only as good as the enforcement and incentive structure around it.** A proposal template doesn't produce proposal culture any more than a written instruction produces compliance. What determines whether people write honest non-goals is whether the last person who did was rewarded or punished for it. **On what he doesn't claim.** *"I'm not certain if repo-parser is exactly the right abstraction... Time will tell."* He built the tool, links it, and declines to argue it's correct. Similarly, the Diataxis quibble is offered with a question mark (*"but I think that's one of its strengths?"*) and the durability evidence for his own best-received document is *"no one has felt motivated to take it down."* **A retrospective this confident in its principles and this hedged about its artifacts is doing the epistemics right.** ## Newsletter **If you write skills, this is the four-line pattern to steal.** William Lachance spent five years away from heavy documentation work and came back to check whether his principles survived LLMs. Mostly they did. But buried in the how-to section is the most useful thing I've read about Agent Skills: > *"Agent Skills which are, at heart, just little markdown docs named SKILL.md which describe how to perform a particular task. I think they are entirely complementary to the approach."* A skill **is** a how-to doc. Same content, different reader. So don't write it twice - write the how-to where humans will find and maintain it, and make the skill a pointer: ```markdown --- name: query-main-ping-telemetry-table description: Query the main ping telemetry table in Bigquery --- Refer to `docs/howtos/query-telemetry-table-in-bigquery.md` ``` That's the whole skill. The always-loaded surface stays four lines, the body lives in the docs tree where it gets reviewed like anything else, and the human and the model read the *same file*, so they can't drift apart. If you've got a skill library where the bodies keep growing and there's nowhere left to push detail, this is the missing floor. His reason for writing procedures down at all, given that models can figure things out unaided: > *"I'm often surprised at how quickly modern large language models can figure out how to do something essentially from first principles, but if you've arrived at a good solution already, why bother doing that? Just give them a cookbook and save the time and the tokens."* And the better half: when it goes wrong, *"the exact set of steps is right there"* - you have something to diff the behaviour against. **The second idea is for anyone letting a model write code.** Lachance kept encoding intent, constraints, and non-goals into prompts, then noticed he was writing a design doc badly: > *"Since I found that I was encoding these details in a prompt, I thought: hey, why not just make the prompt a design doc?"* Human writes problem statement, context, goals, **non-goals**, and a solution sketch. Model collaborates on the detailed design. Then implementation - and **the document gets checked in next to the code**, reviewable in a PR like any other artifact. Filenames borrow from database migrations (`202601180308-upload-packages-to-pypi.md`) because these are moments in time, not current truth. If that sounds like plan mode, he says the difference is deliberate structure, explicit dating, and more human involvement early. The difference he doesn't name is the one I'd emphasise: **plan mode's artifact evaporates.** This one is still there in six months when someone asks why. His diagnosis of why you need it: models *"have the memory of a goldfish,"* AGENTS.md *"can only tell it so much,"* and even with huge context windows *"important facts can be missed or given too little weight."* **And the line to quote at anyone generating reference docs with an LLM:** > *"Even if you can generate a perfect first draft, you've only postponed the problem: the implementation will change, and independently maintained reference documentation will drift from it."* The quality of the draft is irrelevant. Reference docs need to be **derived** from something machine-readable and **linked back** to it, not created once and left. Old idea - Sphinx autodoc, doxygen - and now it's also a hallucination control, because cited ground truth is the thing a human can check the model against. Two more worth carrying. Tutorials *"were actually never really meant to describe how to do something"* - they exist to give someone hands-on success so they'll go deeper. And proposal culture fails not for lack of templates but for lack of psychological safety: *"If people don't feel like their design or feedback is going to be taken in good faith, the proposal process won't work very well."* The whole thing rests on a sentence worth keeping: documentation is *"an act of care both to yourself and your peers, past and present."* ## Action Items **DevRel** - `#action/h1` **The skill-as-pointer pattern is a talk and a blog post.** Concrete, four lines, and it resolves the "do I write this for humans or for the model?" question that everyone building skills hits. - `#action/h1` **"A skill is a how-to doc"** reframes Agent Skills as an application of Diataxis rather than a new discipline - a much better teaching entry point than starting from the SKILL.md spec. - `#action/h2` The tutorial point (*"never really meant to describe how to do something"*) corrects a near-universal misconception and is worth saying out loud at every docs talk. **OSPO** - `#action/h1` **Reference docs must derive from ground truth with links back.** The strongest available argument against LLM-generated reference documentation, and it's about derivation rather than quality. - `#action/h2` **Proposal culture requires psychological safety** - a governance point, not a tooling one. Templates don't produce the behaviour. - `#action/h2` The build-vs-SaaS argument (mapping is 90% of the effort, so spend the last 10% on a fit-for-purpose interface) is a reusable evaluation frame. **Community** - `#action/h2` Decision records checked in beside code are institutional memory that survives contributor turnover - the same argument McCarthy's release-lead decision log makes from the other direction. **WordPress subteams** - **Documentation** - `#action/h1` **The most directly applicable source in this batch for the docs team.** Three items: Diataxis as the organising frame; reference material (hooks, functions, block APIs) should derive from source with links back rather than being hand-maintained; and how-to docs are now dual-audience, read by contributors *and* by models. - **Core AI** - `#action/h1` The design-doc-as-prompt pattern is a concrete practice for any AI-assisted contribution workflow, and the checked-in artifact answers the "how do we review AI-written code" question by giving reviewers the intent to review against. - **Core** - `#action/h2` Dated decision records next to code address exactly the institutional-memory gap that the 7.1 release-lead log and the WP Rocket triage failure both exposed this week. - **Meta** - `#action/h2` Developer reference is already partly source-derived; the link-back-to-source principle and repo-parser's approach are worth comparing against current practice. - **Training** - `#action/h2` The tutorial/how-to distinction is directly applicable to Learn WordPress, especially the point that tutorials exist to produce confidence rather than competence. - **Plugins, Themes** - `#action/h3` Plugin and theme handbooks are prime candidates for the derive-from-source treatment. - **Core Program Team** - `#action/h3` The proposal template (problem - context - goals - non-goals - proposed solution) is lighter than most WordPress proposal formats and the **non-goals** section is the part usually missing. - **Core Performance, Mobile, Photos, TV, Polyglots, Openverse, Marketing, Design, Accessibility, CLI, Playground, Support, Hosting, Tide** - **Not applicable to this source.** **The WPOCC** - `#action/h2` "Write the how-to once, point the skill at it" is a good practical workshop segment - it produces a working artifact in minutes and teaches Diataxis sideways. **FAIR** - Not applicable to this source. **Personal / vault** - `#action/h1` **THE ACTION ITEM OF THIS BATCH. Apply the skill-as-pointer pattern to her skill library.** Measured this session: **159 skills, ~11,709 tokens of always-on descriptions, 30 bodies over 8KB with nowhere to push detail.** Lachance supplies the missing floor - move bodies into `~/.claude/knowledge/wiki/` (which already exists and is already the documented home for durable knowledge) and reduce the SKILL.md to frontmatter plus a pointer. **This is a fix for a problem measured four days ago.** - `#action/h1` **Evaluate the dated-IDR pattern against her plan-mode workflow.** She uses plan mode routinely; the additions are a template, a timestamp, and a checked-in file. The gain is an artifact that survives the session. - `#action/h2` **The wiki should derive from ground truth where it can.** `~/.claude/knowledge/wiki/tools/tool-routing.md` and `model-effort-policy.md` are hand-maintained descriptions of a configuration that changes - exactly the drift Lachance describes. Anything derivable from `settings.json` or the installed skill set should be generated with links back. - `#action/h2` **repo-parser may fit the vault directly.** Its stated input is "a forest of markdown, yaml, and json"; the 2nd Brain vault is precisely that. Worth evaluating against `vault-hygiene-checker`, which currently does its own parsing. - `#action/h2` **"Even if you can generate a perfect first draft, you've only postponed the problem"** - a caution for the vault. Generated reference notes without a derivation path will drift and look maintained while doing it. - `#action/h3` Her CLAUDE.md maintenance note ("prune quarterly, revise from counted failures") is Lachance's *always be improving* already in practice. Worth noting the convergence. ## Hypotheses 1. **The skill-is-a-howto hypothesis.** If a SKILL.md and a how-to doc contain the same content for different readers, then maintaining both duplicates effort and guarantees drift; pointing one at the other eliminates both. *Asserted and demonstrated with a worked example; no adoption data.* 2. **The cookbook-economics hypothesis.** If a model can derive a procedure but a written one exists, the written one is cheaper (tokens, time) and more consistent. *Asserted from practice; no measurement.* 3. **The debuggability hypothesis.** Written procedures give you a reference to diff observed behaviour against; without one you debug against an unstated standard. *Stated briefly and, as reviewer inference, probably the stronger of the two arguments for cookbooks.* 4. **The generation-postpones-drift hypothesis.** A generated reference doc has the same defect as a hand-written one - no derivation path - regardless of draft quality. *The sharpest argument in the piece. Well-reasoned, not measured.* 5. **The ground-truth-as-hallucination-control hypothesis.** Cited, machine-derived reference material reduces hallucination and gives a human something to check against. *Plausible and unmeasured; the second half (human verification) is the more defensible claim.* 6. **The domain-mismatch hypothesis.** A generic catalog's domain (schemas, tables) differs inherently from a business's domain, so mapping cost approaches build cost. *Supported by one detailed case (Google Data Catalog, c. 2020) and generalised confidently.* 7. **The prompt-is-a-design-doc hypothesis.** The information a proposal carries and the information a model needs are the same, so one durable artifact serves both. *His central practical claim; reported from personal practice.* 8. **The psychological-safety-precondition hypothesis.** Proposal culture fails without good-faith engagement, independent of tooling. *Offered as partial explanation, explicitly not fully argued.* 9. **The ephemeral-artifact hypothesis (reviewer inference).** Plan mode's real limitation versus IDRs is that its artifact doesn't persist, not its structure. *He names structure and human involvement; this is the reviewer's addition.* ## Methodology **Design: practitioner retrospective.** Five-year revisit of previously published principles, tested against personal experience with LLMs. **No study, no measurements, no user research, no comparison groups.** Evidence is one person's experience across a named body of public work. | Claim | Basis | Strength | |---|---|---| | Diataxis is a good frame | Personal use plus outcome at Mozilla | **Moderate.** The Mozilla outcome is real but self-reported and confounded; Diataxis is independently well-regarded. | | Emphasising tutorials made the site more useful | **Self-reported**, with a concrete signal (answering Slack questions with step-by-step links) | **Weak-to-moderate.** The signal is genuine but anecdotal, with no baseline. | | The sprawling mixed-type doc was valuable | *"repeated feedback"* from Firefox engineers | **Weak.** Uncounted, unattributed, and the durability evidence - *"no one has felt motivated to take it down"* - is explicitly thin, which he knows. | | Skills are how-to docs | **Structural argument plus a worked example** | **Strong as an argument**, since it rests on what a SKILL.md is rather than on outcomes. No adoption evidence. | | Manual reference docs fail past N entities | The Mozilla NxM case, quoted from 2020 | **Strong for the specific case**; the general threshold is asserted. | | Generation postpones rather than solves drift | **Reasoned argument about derivation** | **Strong.** Doesn't depend on measurement - it's a claim about what a generated artifact is. | | Ground truth reduces hallucination | Asserted | **Weak as stated.** Plausible, unmeasured. The human-verification half is more defensible than the reduction half. | | Generic catalogs mismatch business domains | One detailed 2020 evaluation, generalised | **Moderate**, with a disclosed staleness problem - he says he hasn't looked since. | | "90% of the effort is mapping" | *"in my experience"* | **Weak.** A memorable number with no derivation. | | Design-doc-as-prompt works | Personal practice | **Weak as evidence, strong as a described practice.** No comparison to prompting without it. | | Psychological safety is required | Asserted, explicitly not fully argued | **Appropriately hedged** - he flags it as beyond the article's scope. | **Methodological virtues.** - **Staleness is disclosed rather than hidden.** He left Mozilla in January 2022, says so, and repeats it: *"I haven't really been involved in the community or watching closely."* The Google Data Catalog assessment carries its own caveat: *"I haven't looked... since then."* - **His own tools are hedged, not sold.** *"I'm not certain if repo-parser is exactly the right abstraction... Time will tell."* Someone with a framework to promote does not usually write that. - **Uncertainty is punctuated.** *"but I think that's one of its strengths?"* - the question mark is doing real work. - **Sources are named across five decades**, and he explicitly declines to claim novelty: Design Docs at Google (2015), Spolsky (2000), *"all the back to the 70s, or even earlier."* - **He disagrees with his own framework.** The Diataxis quibble, with a counterexample from his own writing, is a small thing that signals he's using the framework rather than reciting it. **What is not established.** - **Nothing here is measured.** Every efficacy claim is one practitioner's experience, and the LLM-era claims (skill-as-pointer, design-doc-as-prompt) are the newest and least tested. - **No negative cases.** Situations where these practices failed, or cost more than they returned, don't appear. Documentation retrospectives are a genre where survivorship is the default. - **The Mozilla evidence is five to six years old** and, by his own account, unverified since. - **"90% of the effort"** and *"hundreds or thousands of entities"* are gestures at magnitude, not derived figures - mild `#fallacy/false-precision`, though both are hedged in context. - **No cost side.** IDRs add friction; maintaining derive-from-source infrastructure is real engineering. Neither is priced. **Bias checks.** *Vendor interest* - **none**; personal blog, two open-source projects, both hedged. *Survivorship* - **present**, as in most practitioner retrospectives; only practices that worked are described. *Self-reported metrics* - pervasive but generally labelled as personal experience rather than dressed as data. *Newer-is-better* - **actively resisted**, which is the piece's most distinctive methodological feature: the repeated conclusion is that LLMs changed *less* than expected. *Anecdote generalised* - present in the Data Catalog argument, where one 2020 evaluation supports a claim about SaaS catalogs generally. ## Questions 1. **What does the full IDR template and workflow look like in practice?** The post shows a truncated example ending at *"### Proposed Solution ..."*. The tooling is in `idr-tools` and unread here - **the most actionable unanswered question**. 2. **How does the skill-as-pointer pattern behave with progressive disclosure?** If the skill body is one line, when does the model actually read the referenced file? This matters for whether the pattern saves context or just moves it. 3. **What's the failure rate of design-doc-as-prompt?** He reports it works. Cases where the doc was written and the implementation still went wrong would be more informative. 4. **Does repo-parser fit a personal knowledge vault**, not just a code repository? Its stated input matches, but the use cases described are all engineering. 5. **What's the maintenance cost of derive-from-source infrastructure?** The Glean Dictionary required probe-scraper and mozilla-schema-generator. That's real ongoing engineering, unpriced here. 6. **Has any of this been tested against a team, or only solo?** The LLM-era practices read as personal workflow; proposal culture is inherently collective. 7. **Where does the 90% mapping figure come from?** Memorable, load-bearing for the build-vs-buy argument, and underived. 8. **How current is the Data Catalog critique?** He flags it as stale himself; the market has moved substantially since 2020. ## Future Research - **Read `idr-tools` and the sample IDRs** in that repo and in repo-parser's `idrs` subdirectory. The template is the actionable artifact and the post only excerpts it. - **Test the skill-as-pointer pattern on two or three real skills** and measure the context effect - does it reduce loaded tokens, and does the referenced file actually get read when needed? Directly checkable against a known baseline. - **Evaluate repo-parser against the 2nd Brain vault.** A markdown-plus-frontmatter forest is its stated input, and `vault-hygiene-checker` currently rolls its own parsing. - **Audit the wiki for derivable content.** `tool-routing.md` and `model-effort-policy.md` describe configuration that exists in machine-readable form elsewhere; anything derivable should be generated with links back. - **Read Design Docs at Google and Spolsky's functional specifications** - the lineage he cites, useful for arguing this is settled practice. - **Look for the negative cases.** Teams that adopted proposal culture and abandoned it would test the psychological-safety hypothesis better than success stories. ## Implications **Practice.** Two concrete changes and one caution. **Write how-to content once and point skills at it** - the deduplication is free and the drift elimination is the real gain. **Give model-implemented work a dated, structured, checked-in design document** instead of an ephemeral prompt. And **don't generate reference documentation**: derive it, or accept that it will drift while looking maintained. **Policy.** The psychological-safety point is a governance claim wearing documentation clothes. **A proposal template does not produce proposal culture**, any more than a written instruction produces compliance - which is the same conclusion that surfaced four separate times in this week's reading under the heading of enforcement boundaries. What determines whether people write honest non-goals is what happened to the last person who did. **Security.** Only tangential, but real: **cited ground truth gives a human operator something to check a model's output against.** The alt-text source in this same batch made the complementary point from the other side - findings are prompts for human attention, not verdicts. Both reduce to: automation is trustworthy in proportion to how cheaply a human can verify it. **Education.** *"Tutorials were actually never really meant to describe how to do something."* Their job is a first success that produces the confidence to go deeper. That reframes tutorial-writing from coverage to momentum, and it's the single most commonly-violated principle in technical education. **For Courtney's practice, and this is why the source matters most.** The skill-as-pointer pattern **resolves a problem measured in this session** - 159 skills, ~11,709 always-on tokens, 30 oversized bodies with nowhere to push detail. The missing floor was never missing; it's `~/.claude/knowledge/wiki/`, which her own CLAUDE.md already designates as the home for durable knowledge. Beyond that, the ground-truth principle applies directly to that wiki (parts of it describe configuration that exists machine-readably elsewhere and will drift), and the IDR pattern is a small, testable upgrade to a plan-mode workflow she already runs. ## Learning Styles Assessment - **Visual** - Weak. One Diataxis quadrant diagram, one screenshot of a repo-parser site, one screenshot of a commit history. The IDR workflow and the ground-truth derivation pipeline both want diagrams and get prose. - **Aural** - Not applicable to this source. - **Verbal** - **Strong.** Conversational, precise, and willing to be funny (*"the memory of a goldfish"*, an emoji in an aside about Mozilla). Complex ideas land in single sentences. - **Kinesthetic** - **Strong.** A copy-pasteable skill file, a filename convention, a document template, and two linked repositories. Several things here can be tried in under ten minutes. - **Logical** - **Strong.** Explicit structure: four principles, each revisited, each asked the same question about LLMs. The "almost not at all / totally" split is a clean way to hold two answers at once. - **Social** - **Moderate to strong.** Heavy on named prior art and colleagues' contributions (*"my coworkers wrote and presented on them extremely effectively"*), and the psychological-safety section is fundamentally about how people treat each other. - **Solitary** - Strong. Self-contained; the links deepen rather than gate. - **Naturalistic** - Not applicable to this source. **Reading level estimate.** Roughly grade 13-14. Assumes familiarity with documentation practice, data engineering vocabulary (BigQuery, schemas, pings, metrics), and current LLM tooling (AGENTS.md, plan mode, Agent Skills). The Mozilla telemetry examples are the steepest part and are illustrative rather than load-bearing - a reader can skip them and lose nothing structural. ## Accessibility Assessment Mapped to WCAG 2.2 AA, assessed from the captured text: 1. **Perceivable - non-text content (1.1.1).** **Partial concern.** Three images appear in the capture - the Diataxis quadrant diagram, a repo-parser site screenshot, and a commit-history screenshot. Their extracted text reads as terse caption-like strings (*"Diataxis: tutorials, howtos, explanations, reference"*, *"repo-parser doc site"*). For the **Diataxis diagram this is adequate** - the four labels are the content. For the **screenshots it likely isn't**: a screenshot of generated documentation illustrating what the tool produces carries information the phrase "repo-parser doc site" doesn't convey. The surrounding prose does describe the content (*"produced from a README.md inside the repository, collected and organized dynamically at build-time"*), which substantially mitigates it. 2. **Perceivable - info and relationships (1.3.1).** **Pass.** Clear heading hierarchy matching the four principles, real lists, blockquotes for self-quotation, code blocks preserved. 3. **Perceivable - contrast (1.4.3, 1.4.11).** Not assessable from the scrape. **Not assessed.** 4. **Operable - link purpose (2.4.4).** **Good.** Links are descriptive in context - named article titles, named repositories. One weak instance: a bare `https://dictionary.telemetry.mozilla.org/...` URL used as an inline example rather than a navigational link, which is defensible since the URL *is* the illustration. 5. **Operable - timing, seizures (2.2, 2.3.1).** No timed or moving content. **Pass.** 6. **Understandable - language and readability (3.1).** **Mixed.** Prose is conversational and clear, and Diataxis is defined before use. But BigQuery, pings, probes, metrics, Glean, and AGENTS.md all arrive unexplained. The Mozilla-specific vocabulary is dense in the middle third. 7. **Robust - parsing (4.1).** **Pass.** Clean extraction; footnotes with return markers survived, code blocks intact. **Notable good practice:** proper **footnotes with return links** (the return markers came through), which is a real navigational courtesy and frequently botched on personal blogs. **Highest-value remediation:** fuller alt text on the two screenshots, and a diagram of the IDR workflow - the most reusable idea in the piece exists only as prose. ## DEIB Assessment - **Psychological safety - named explicitly, and that's unusual.** Most documentation writing treats proposal culture as a tooling problem. Lachance names the social precondition directly: *"If people don't feel like their design or feedback is going to be taken in good faith, the proposal process won't work very well. People will be hesitant to put things out there and to engage, and the opportunity for learning will be reduced."* And the positive version - in a healthy workplace *"people are constantly being guided towards presenting their best ideas, with the knowledge that their colleagues are there to support them."* **That is a genuine inclusion argument**: who feels safe circulating a half-formed design is not evenly distributed, and a proposal culture without safety systematically privileges the already-confident. - **Framing documentation as care.** *"Fundamentally, it's an act of care both to yourself and your peers, past and present."* And on continuous improvement: *"an (infectious) demonstration of actual care. It's a way of supporting others, including your future self."* Framing infrastructure work as relational rather than mechanical is a small thing that shapes who sees themselves in it - documentation labour is chronically undervalued and disproportionately done by people who aren't credited for it. - **Accessibility of onboarding - the strongest implicit point.** The tutorial argument is inclusion reasoning without the label: tutorials exist to produce a *feeling of success* so newcomers gain confidence to go further. Systems that skip that step are navigable only by people who already have context, which selects for prior access. - **Inclusive language.** Good. Neutral throughout, no gendered defaults, no ability metaphors. Colleagues are credited generously (*"myself and a few of my coworkers"*, *"my coworkers wrote and presented on them extremely effectively"*). - **Representation.** Named individuals are limited to Joel Spolsky and the implied Diataxis author (Daniele Procida, unnamed here). Mozilla colleagues are credited collectively but never by name - a common and slightly flattening convention in retrospectives, though the crediting impulse is clearly present. - **Geographic and organisational framing.** Entirely within a Mozilla / Google / open-source-tooling frame. Fair, since it's what he can speak to and he says so - but the conclusions are generalised to organisations broadly, and well-resourced engineering orgs are a narrow base for that. ## Logical Validity **Strong reasoning.** 1. **A consistent test applied to every principle.** Each of the four gets the same question - what did LLMs change? - and the answers vary honestly: *no* for Diataxis, *most and least* for how-tos, *"almost not at all" and "totally"* for proposals. **A retrospective that reached the same verdict four times would be suspect.** 2. **The generation-postpones-drift argument is structurally sound.** It doesn't depend on draft quality, which is what makes it strong: a perfect generated draft has the identical defect as a poor one, because the defect is the missing derivation path. 3. **The skill-as-pointer argument rests on what a thing is, not on outcomes.** A SKILL.md and a how-to have the same content and different readers; therefore point one at the other. No efficacy data needed for the argument to hold. 4. **Staleness is disclosed, repeatedly.** Left Mozilla January 2022, hasn't followed since, hasn't re-examined Data Catalog. He inoculates his own claims. 5. **His own tools are hedged.** *"I'm not certain if repo-parser is exactly the right abstraction... Time will tell."* Rare from someone with a framework to promote. 6. **He disagrees with his preferred framework.** The Diataxis quibble, with a counterexample from his own writing, demonstrates use rather than recitation. 7. **Novelty is explicitly refused.** Design Docs at Google (2015), Spolsky (2000), *"all the back to the 70s"* - he positions his contribution as application rather than invention. 8. **A puzzle is posed and only partly answered.** *"If the ideas are so obvious, why?"* - then a partial answer flagged as beyond scope. Not pretending to a complete explanation. **Fallacies and weaknesses.** 1. **Survivorship throughout** - `#fallacy/survivorship-bias`. Only practices that worked are described. No abandoned approach, no case where an IDR was written and the work still failed, no proposal culture that collapsed. Endemic to the genre and unaddressed here. 2. **Personal experience generalised to organisations** - `#fallacy/hasty-generalization`. The LLM-era claims come from one person's solo workflow and are offered as general practice. Mild, since he uses first-person consistently, but the recommendations don't carry the same hedge the evidence does. 3. **"90% of the effort"** - `#fallacy/false-precision`. Load-bearing for build-vs-buy, derived from nothing, softened only by *"in my experience."* 4. **The Data Catalog critique is stale and generalised** - `#fallacy/hasty-generalization`. One 2020 evaluation supports a claim about SaaS catalogs across industries. **He discloses the staleness**, which converts this from a flaw into a labelled limitation. 5. **No cost accounting** - `#fallacy/suppressed-evidence`, mild. IDRs add friction; derive-from-source infrastructure is ongoing engineering (probe-scraper, mozilla-schema-generator). Benefits are argued, costs aren't priced. 6. **Thin evidence presented as evidence** - *"no one has felt motivated to take it down"* as durability proof. **He flags its weakness himself** (*"I can't be totally certain"*), which is the right handling of a weak signal. 7. **Ground truth as hallucination defense is asserted** - `#fallacy/unfalsifiable-claim`, mild. The verification half is defensible; the reduction half is unmeasured. **Tone of voice.** Conversational, self-deprecating, and comfortable being uncertain in public. Question marks used as genuine hedges rather than rhetorical devices. Willing to be funny without undercutting the argument (*"the memory of a goldfish"*). The dominant register is **a practitioner thinking out loud with the receipts attached** - every claim about his past work links to the public artifact. What's most notable is the absence of the two registers this topic usually attracts: **no evangelism about documentation, and no anxiety about LLMs.** The repeated finding that things changed less than expected is delivered without either relief or disappointment. ## DARVO Analysis **Not applicable to this source.** DARVO describes a pattern in accounts of wrongdoing - denial, attacking the accuser, reversing victim and offender. This is a technical retrospective on documentation practice. No accusation, no accused, no contested harm. **Two adjacent observations worth recording.** **First**, where the piece touches organisational failure - *"many organizations struggle to have a good proposal culture"* - the analysis is **structural rather than accusatory**. He attributes the failure to absent psychological safety, a systems condition, rather than to bad actors or insufficient discipline. That is the opposite of a blame-assignment move. **Second**, on his former employer: he left Mozilla in January 2022 and could have written this with grievance or triumph. He does neither, and takes care to leave room for the organisation to have moved on without him: *"Likely the internal perspective at Mozilla these days is different from my own (hopefully not that different)"*. **A retrospective on a former workplace with no score-settling in it** is worth noting as a clean negative finding - this is the third source in this batch (with Ginder and WP Rocket) that declines an available grievance framing. ## Conclusion **Bottom line.** A five-year retrospective whose main finding is that LLMs changed less than expected - and which, almost in passing, supplies the most immediately useful pattern in this batch. **The pattern:** an Agent Skill is a how-to document with a different reader. So write the how-to once, where humans will maintain it, and make the skill a pointer: ```markdown --- name: query-main-ping-telemetry-table description: Query the main ping telemetry table in Bigquery --- Refer to `docs/howtos/query-telemetry-table-in-bigquery.md` ``` **This resolves a problem measured in this very session** - 159 skills, ~11,709 tokens of always-on descriptions, and 30 skill bodies over 8KB with nowhere to push detail. The diagnosis then was that progressive disclosure needs a floor beneath the SKILL.md. Lachance's answer is that the floor already exists: it's the documentation tree. In her case, `~/.claude/knowledge/wiki/`, which her own CLAUDE.md already names as the home for durable knowledge. **The argument for writing procedures at all**, given that capable models can derive them: *"if you've arrived at a good solution already, why bother doing that? Just give them a cookbook and save the time and the tokens."* And the better half - when a run goes wrong, *"the exact set of steps is right there"* to diff the behaviour against. **The sharpest reasoning in the piece** is about reference documentation: *"Even if you can generate a perfect first draft, you've only postponed the problem."* Draft quality is irrelevant, because **the defect is the missing derivation path.** Reference docs must be derived from something machine-readable and linked back to it. Old idea - Sphinx autodoc, doxygen - and now also a hallucination control, since cited ground truth is what a human checks the model against. **The second practice worth adopting:** *"why not just make the prompt a design doc?"* Intent, goals, non-goals, and a solution sketch in dated markdown; the model collaborates on detailed design; the document gets **checked in beside the code** and reviewed in a PR. Against plan mode he cites structure and earlier human involvement; the difference he doesn't name is that **plan mode's artifact evaporates and this one is still there in six months.** **The caveats are real and mostly self-disclosed.** Nothing is measured - every efficacy claim is one practitioner's experience, and the LLM-era practices are the newest and least tested. No negative cases appear, which is the standing weakness of the genre. The Mozilla evidence is five years old and unverified since, and he says so twice. "90% of the effort" is a memorable number with no derivation. **What makes it credible anyway** is the hedging pattern: his own framework gets a counterexample, his own tool gets *"I'm not certain if repo-parser is exactly the right abstraction... Time will tell,"* his own best-received document gets *"I can't be totally certain it still holds up,"* and his novelty claim gets refused outright in favour of citations back to 2000 and 2015. **And the governance point that connects to the rest of this week's reading:** proposal culture fails not for want of templates but for want of psychological safety. **A template no more produces proposal culture than a written instruction produces compliance** - which is the fifth independent appearance of the enforcement-boundaries finding in this batch. The whole thing rests on a premise worth keeping: documentation is *"an act of care both to yourself and your peers, past and present."* **Next steps.** 1. **Apply skill-as-pointer to the skill library** - highest-value action in this batch, and a fix for a measured problem. 2. **Read `idr-tools`** for the full template; the post only excerpts it. 3. **Audit the wiki for derivable content** - anything describing configuration that exists machine-readably should be generated with links back. ## Refactor Appendix ### Literature Split Pad (H3) > [!quote] `#atom/literature/h1` > "Early in 2026, the hot topic was creating Agent Skills which are, at heart, just little markdown docs named SKILL.md which describe how to perform a particular task. I think they are entirely complementary to the approach. You write a detailed howto describing how to perform a task... An LLM can process a well-written markdown file just as easily as a human: just create an appropriate skill file saying as such" **The most immediately useful passage in this batch.** A skill is a how-to doc with a different reader. Write once, point the skill at it - the always-loaded surface stays tiny and human and model read the same file, so they can't drift. > [!quote] `#atom/literature/h1` > "I'm often surprised at how quickly modern large language models can figure out how to do something essentially from first principles, but if you've arrived at a good solution already, why bother doing that? Just give them a cookbook and save the time and the tokens." Settles the "are written procedures obsolete?" question on economic rather than epistemic grounds. Plus debuggability: *"the exact set of steps is right there."* > [!quote] `#atom/literature/h1` > "Even if you can generate a perfect first draft, you've only postponed the problem: the implementation will change, and independently maintained reference documentation will drift from it." **The correct objection to LLM-generated reference documentation.** Draft quality is irrelevant; the defect is the missing derivation path. > [!quote] `#atom/literature/h1` > "Since I found that I was encoding these details in a prompt, I thought: hey, why not just make the prompt a design doc?" The design-doc-as-prompt move. A proposal and a model brief contain the same information, so write it once in a durable, dated, checked-in format. > [!quote] `#atom/literature/h2` > "since they have the memory of a goldfish, I've found getting them to produce the right thing a bit of a crapshoot. Yes, there is AGENTS.md but that can only tell it so much: there's always more 'implicit' context that is needed to solve a problem of any complexity. And even with extremely long context, important facts can be missed or given too little weight." The problem statement for the IDR pattern. Long context is not the same as weighted context. > [!quote] `#atom/literature/h2` > "The key difference is a fairly deliberate structure (explicit dating and proposal template) and a higher level of human involvement in the earlier stages of design." His stated contrast with plan mode. The unstated third difference - the artifact persists - is arguably the largest. > [!quote] `#atom/literature/h2` > "as we delegate more of the day-to-day work to machines and reduce the amount of hands-on work which generates understanding, our need for these aids has only increased." Why tutorials and explanations matter *more* under delegation, not less. Doing the work is how understanding gets generated; delegating it removes the generator. > [!quote] `#atom/literature/h2` > "Having a clear statement of the system-as-it-currently-is (with citations) is the best defense against that. Not only does it reduce the chance of hallucination or confabulation, but it gives a human operator the chance to check the reference and see if it makes sense." Ground truth as hallucination control. The second half - cheap human verification - is the more defensible claim. > [!quote] `#atom/literature/h2` > "I do think that having an effective proposal requires a strong commitment to psychological safety. If people don't feel like their design or feedback is going to be taken in good faith, the proposal process won't work very well." Fifth independent appearance of enforcement boundaries this batch: the template is not the mechanism. > [!quote] `#atom/literature/h3` > "One thing that many people find surprising about tutorials is that they were actually never really meant to describe how to do something. Instead, the purpose is primarily just to give some hands-on experience and feeling of success" Tutorials produce confidence, not competence. The most commonly violated principle in technical education. > [!quote] `#atom/literature/h3` > "unless your product is a database, the domain of a generic data catalog (schemas, tables) is going to be inherently different than that of your business." The domain-mismatch argument for build-over-buy. Mapping cost is *"honestly 90% of the effort"* - hedged, underived, and memorable. > [!quote] `#atom/literature/h3` > "Fundamentally, it's an act of care both to yourself and your peers, past and present." The premise under the whole piece. Documentation as relational rather than mechanical work. > [!quote] `#atom/literature/h3` > "I'm not certain if repo-parser is exactly the right abstraction for building something like this, or if it's more like an architectural design pattern where every implementation is bespoke. Time will tell." Hedging his own framework. The reason the rest of the piece's confidence reads as earned. ### Atomic Split Pad (H4) - `#atom/zettel/z1` **A skill is a how-to doc with a different reader** - Same content, different audience. Writing both duplicates effort and guarantees drift; making the skill a pointer to the doc eliminates both and keeps the always-loaded surface minimal. - `#atom/zettel/z1` **A cookbook beats derivation even when derivation works** - A capable model can reconstruct a procedure, but at token cost, latency cost, and with run-to-run variance. A written procedure is free, instant, identical every time, and gives you something to diff behaviour against when it goes wrong. - `#atom/zettel/z1` **Generated reference documentation postpones drift rather than solving it** - The defect isn't draft quality, it's the absent derivation path. A perfect generated draft decays exactly like a hand-written one, while looking maintained. - `#atom/zettel/z1` **Reference documentation must derive from ground truth and link back to it** - The link matters as much as the derivation: it lets a reader verify the assertion rather than trust it, which is what makes cited reference material a hallucination control. - `#atom/zettel/z1` **A prompt and a design document carry the same information** - Intent, goals, non-goals, constraints, solution sketch. Writing it once in a dated, structured, checked-in file serves the model now and the reader later. - `#atom/zettel/z1` **A persistent artifact beats an ephemeral plan** - Approving a plan in-session leaves nothing behind. A dated document beside the code answers "why is this like this?" months later, and can be reviewed like any other artifact. - `#atom/zettel/z1` **Long context is not weighted context** - *"important facts can be missed or given too little weight."* Fitting information into the window does not determine what the model attends to; structure and placement still do work that raw capacity does not. - `#atom/zettel/z1` **Tutorials produce confidence, not competence** - Their purpose is a first hands-on success that makes deeper material approachable. Judging a tutorial by coverage is judging it against a goal it never had. - `#atom/zettel/z1` **Delegation increases the need for explanation** - Hands-on work is what generates understanding. Removing it removes the generator, so the documents that supply understanding directly become more necessary, not less. - `#atom/zettel/z1` **A template does not produce a culture** - Proposal practice requires psychological safety; without good-faith engagement people write defensively or not at all. The artifact is downstream of the incentive. - `#atom/zettel/z1` **Mapping to a generic tool costs nearly as much as building a specific one** - When a cross-industry product's domain differs from yours, translation is most of the work, and the remainder buys a fit-for-purpose interface. ### Fleeting Queue - `#atom/fleeting/f1` **APPLY SKILL-AS-POINTER TO THE SKILL LIBRARY.** 159 skills, ~11,709 always-on tokens, 30 bodies over 8KB. Move bodies to `~/.claude/knowledge/wiki/`, reduce SKILL.md to frontmatter plus a pointer. **A fix for a problem measured four days ago.** - `#atom/fleeting/f1` **Read `idr-tools`** - the full template and workflow. The post excerpts and truncates it. - `#atom/fleeting/f1` **Test the IDR pattern against plan mode** on one real task. Additions are a template, a timestamp, a checked-in file. - `#atom/fleeting/f1` **Audit `~/.claude/knowledge/wiki/` for derivable content** - `tool-routing.md` and `model-effort-policy.md` describe configuration that exists machine-readably. Generate with links back. - `#atom/fleeting/f1` **Evaluate repo-parser against the 2nd Brain vault** - "a forest of markdown, yaml, and json" is its stated input and an exact description of the vault. Compare against `vault-hygiene-checker`'s own parsing. - `#atom/fleeting/f1` **Verify the skill-as-pointer context effect** - does a one-line body actually reduce loaded tokens, and does the referenced file get read when needed? Measurable against a known baseline. - `#atom/fleeting/f1` **Fifth enforcement-boundaries sighting this batch** (psychological safety as the precondition for proposal culture). Joins Theo/Lauren's elimination ladder, Ginder's fleet probe, the AI team's read-only annotations, and the Secrets API filter argument. **This is now the dominant cross-source theme of the week.** - `#atom/fleeting/f1` Her CLAUDE.md maintenance rule (prune quarterly, revise from counted failures) is *always be improving* already in practice - worth noting the independent convergence. - `#atom/fleeting/f1` **Third source in this batch to decline an available grievance framing** (with Ginder and WP Rocket). Possibly worth tracking as a norm rather than a coincidence. ## Template Library ### -> Fleeting refactor Two-line capture: *Lachance's docs retrospective - a SKILL.md is just a how-to doc, so point it at one instead of duplicating: four lines of frontmatter plus "Refer to docs/howtos/x.md". Also "make the prompt a design doc" (dated, structured, checked in) and "even a perfect generated draft only postpones the drift."* File under AI methods and documentation. Revisit when next editing the skill library. ### -> Literature refactor Three destinations. **"Documentation Architecture"** - Diataxis, the tutorial-confidence point, ground-truth derivation, the build-vs-buy argument. **"Skills as Documentation"** - a new note anchored on the skill-as-pointer pattern, which should also absorb the progressive-disclosure measurements from this session's methods review. And **"Enforcement Boundaries"** - the existing topic note gets its fifth source, with psychological safety as the precondition for proposal culture. ### -> Atomic refactor Strongest Permanent Note candidates: 1. **"A Skill Is a How-To Doc With a Different Reader"** - the highest-value atom in this batch. Immediately actionable, fixes a measured problem, and reframes Agent Skills as an application of Diataxis rather than a new discipline. 2. **"Generated Reference Documentation Postpones Drift"** - a clean structural argument that doesn't depend on measurement, and a useful counterweight to the assumption that a good enough model solves documentation. 3. **"A Persistent Artifact Beats an Ephemeral Plan"** - pairs with the decision-log material from McCarthy's release log and the triage-ownership finding from WP Rocket. Three sources this week converge on: *the record is the mechanism.* 4. **"A Template Does Not Produce a Culture"** - the fifth enforcement-boundaries instance. At five independent sources, this stops being a theme and becomes a conclusion. ### -> Things 3 - Apply skill-as-pointer to the skill library; start with the 30 bodies over 8KB (**high priority** - fixes a measured problem, and the wiki floor already exists). - Read `idr-tools` and extract the full IDR template (high priority - the actionable artifact the post only excerpts). - Audit `~/.claude/knowledge/wiki/` for content that should derive from ground truth (medium priority). - Test the IDR pattern against plan mode on one real task (medium priority). - Evaluate repo-parser against the vault (low priority - speculative fit, but the input format matches exactly). <!-- deep-read:sections end --> 📄 **Full text:** [[Full Document Contents/Articles/Writing the Docs 2026 Edition.md|Writing the Docs: 2026 Edition by William Lachance (wlach)]] ## Highlights - One thing that many people find surprising about tutorials is that they were actually never really meant to describe *how* to do something. Instead, the purpose is primarily just to give some hands-on experience and feeling of success, so they can start feeling more confident in going deeper and doing the more advanced tasks where explanation, how-to, and reference become more important. This need to gain a preliminary understanding of the system has not gone away at all with LLMs-- I maintain that hands-on learning and action is still the best way for most people to learn anything, including how to work with computational systems. Once you've gone beyond the basics, any gaps in understanding or context can be filled in by absorbing the content of deeper articles describing the concepts of a system and why it is the way it is. ([View Highlight](https://read.readwise.io/read/01m0z1j9xccfjagc3a86ext8nj)) - Note: Tutorials produce CONFIDENCE, not competence. Judging a tutorial by coverage is judging it against a goal it never had — the most commonly violated principle in technical education, and directly applicable to Learn WordPress and to WPOCC workshop design. Also an implicit inclusion argument: systems that skip the first-success step are navigable only by people who already have context. #atom/zettel/z1 - Of course now, often it's a large language model or similar executing these types of tasks. Early in 2026, the hot topic was creating [Agent Skills](https://agentskills.io) which are, at heart, just little markdown docs named `SKILL.md` which describe how to perform a particular task. I think they are entirely complementary to the approach. You write a detailed howto describing how to perform a task (using Mozilla data as an example, query a table in BigQuery). An LLM can process a well-written markdown file just as easily as a human: just create an appropriate skill file saying as such: ([View Highlight](https://read.readwise.io/read/01m0z1gg8dhq9885jj13fdqapw)) - Note: THE ACTION ITEM OF THIS BATCH. A skill IS a how-to doc — same content, different reader. So don't write it twice: write the how-to where humans maintain it, make the SKILL.md four lines of frontmatter plus "Refer to docs/howtos/x.md". FIXES A PROBLEM MEASURED THIS SESSION: 159 skills, ~11,709 tokens of always-on descriptions, 30 bodies over 8KB with nowhere to push detail. The missing floor was never missing — it's ~/.claude/knowledge/wiki/, which her own CLAUDE.md already names as the home for durable knowledge. #atom/zettel/z1 - I'm often surprised at how quickly modern large language models can figure out how to do something essentially from first principles, but if you've arrived at a good solution already, why bother doing that? Just give them a cookbook and save the time and the tokens. And if you need to debug what it's doing (or do part of it yourself), the exact set of steps is right there. ([View Highlight](https://read.readwise.io/read/01m0z1grd8bzebfq31jnvxf052)) - Note: Settles "are written procedures obsolete now that models can derive them?" on economic rather than epistemic grounds: derivation costs tokens and latency and varies run to run; a cookbook is free, instant, identical every time. The second sentence is the stronger argument — when a run goes wrong, a written procedure gives you something to DIFF the behaviour against. Without one you're debugging a black box against an unstated standard. #atom/zettel/z1 - I was already thinking about the [Glean Dictionary](https://dictionary.telemetry.mozilla.org) and trying to justify working on it to my peers and upper management. In retrospect, this claim is self-evident: if you're dealing with hundreds or thousands of entities (or more), a manual approach to writing the documentation just isn't going to work. Even if you can generate a perfect first draft, you've only postponed the problem: the implementation *will* change, and independently maintained reference documentation will drift from it. ([View Highlight](https://read.readwise.io/read/01m0z1has5dfz9x1m41nfjp7w9)) - Note: THE CORRECT OBJECTION TO LLM-GENERATED REFERENCE DOCS, and it's structural rather than about quality — a perfect generated draft has the identical defect as a poor one, because the defect is the MISSING DERIVATION PATH. Generation makes drift invisible by producing something that looks maintained. Reference docs need to be derived from a machine-readable source and linked back to it. Caution for the vault. #atom/zettel/z1 - Some issues go well beyond the scope of this article: I do think that having an effective proposal requires a strong commitment to [psychological safety](https://archive.wrla.ch/blog/2021/10/learning-about-psychological-safety-at-the-recurse-center/). If people don't feel like their design or feedback is going to be taken in good faith, the proposal process won't work very well. People will be hesitant to put things out there and to engage, and the opportunity for learning will be reduced. In a healthy workplace, people are constantly being guided towards presenting their best ideas, with the knowledge that their colleagues are there to support them. ([View Highlight](https://read.readwise.io/read/01m0z1hzmyer3sav7e7bqfbjmf)) - Note: FIFTH independent enforcement-boundaries sighting this week — joins Theo/Lauren's elimination ladder, Ginder's fleet probe, the AI team's read-only annotations, and the Secrets API filter argument. A template no more produces proposal culture than a written instruction produces compliance. What determines whether people write honest non-goals is what happened to the last person who did. At five sources this stops being a theme and becomes a conclusion. #atom/zettel/z1 - These days, I spend more of my time prompting an LLM than writing code myself. But since they have the memory of a goldfish, I’ve found getting them to produce the right thing a bit of a crapshoot. Yes, there is [AGENTS.md](http://AGENTS.md) but that can only tell it so much: there’s always more “implicit” context that is needed to solve a problem of any complexity. And even with extremely long context, important facts can be missed or given too little weight. ([View Highlight](https://read.readwise.io/read/01m0z1hmf7tz69nx43sakf0xb0)) - Note: The problem statement for the IDR pattern, and the last sentence is the durable atom: LONG CONTEXT IS NOT WEIGHTED CONTEXT. Fitting information into the window does not determine what the model attends to — structure and placement still do work that raw capacity does not. Directly relevant to her 1M-context sessions and to CLAUDE.md sizing. #atom/zettel/z1 - Since I found that I was encoding these details in a prompt, I thought: *hey, why not just make the prompt a design doc*? Have a human express the intent, goals, non-goals and a sketch of a solution in a markdown document and then *collaborate* with an LLM on the detailed design. Then, once you’re happy with the result, proceed with implementation. The result can then be checked in along with the code as a sort of guide to understanding what was done. In a pull request type work flow, it can be critiqued or commented on like any other code artifact. ([View Highlight](https://read.readwise.io/read/01m0z1h20gmfzty61nsvz6qm1b)) - Note: A proposal and a model brief carry the SAME information — intent, goals, non-goals, constraints, solution sketch — so write it once in a durable format. Three properties make it better than a prompt: DATED (reads as a moment in time, not current truth), STRUCTURED (the non-goals section forces the thinking people skip), and CHECKED IN (reviewable in a PR, readable by whoever inherits the code). Test this against her plan-mode workflow. #atom/literature/h1