# Documentation & Technical Writing MOC ## Synthesis additions (2026-10-15 — docs that coding agents read: retrieval, routing, build pipelines, first-run gates) - [[3. Resources/Permanent Notes/Serving Clean Markdown Solves Retrieval but Not Discovery]] — serving markdown by path doesn't tell an agent which page answers its question (Sepic) - [[3. Resources/Permanent Notes/A Docs Page Must State Its Purpose in the Title and Opening Because Agents Lose Navigation]] — context that lives only in the sidebar is lost when an agent receives a chunk (Washington) - [[3. Resources/Permanent Notes/Agent-Facing Docs Are a Build Artifact With a Pipeline and Tests]] — a skill file, markdown mirror or llms.txt is generated output and needs a build, version and tests (Whinnery) - [[3. Resources/Permanent Notes/A Shared Gate Definition Turns Onboarding Complaints Into a Count Product Can Dispute]] — count the gates between arrival and first success on one real route before arguing onboarding is hard (Save) ## Synthesis additions (2026-09-26 — the runnable prompt as a quickstart artifact; friction as the leading docs signal) - [[3. Resources/Readwise/Articles/Optimizing Developer Experience for High Engineering Performance A Roadmap for Enterprises to Reduce Friction, Measure Impact, and Scale Productivity in Software Delivery]] — LF Research (2026-09-18): developers need uninterrupted time and a low-friction path to first result; docs are one of the friction surfaces the report says to measure before outcomes move - [[3. Resources/Permanent Notes/A Paste-Ready Prompt Is Now a Quickstart Artifact]] — Permanent from the Tessa Mero interview: "Copy Prompt" is the new "Copy Code", so a quickstart without one is incomplete The topic map for documentation as a discipline: how docs create value, how that value is measured, what changes when machines read them, and how a docs function is governed when headcount stays flat. Sits under [[3. Resources/MOCs/DevRel MOC]] as an adjacent discipline and next to [[3. Resources/MOCs/Accessibility & Disability Inclusion MOC]]. Event recordings live in their own maps and hang off this one; the first is [[3. Resources/MOCs/Events/Write the Docs Berlin 2026 MOC]]. ## Core Question Documentation is now read by two audiences, people and agents, and produced with tools that make drafting cheap. Which parts of the craft carry over unchanged, which measurements still mean something, and where does human judgment have to sit for the docs to stay trustworthy? --- ## 📐 Docs as product and infrastructure The claims about what documentation *is*, before any question of how to measure or produce it. - [[3. Resources/Permanent Notes/Documentation Is Dual-Audience Infrastructure]] — reference docs now serve machines as well as people, so publishing format is a cost on every reader's compute bill, not a presentation choice - [[3. Resources/Permanent Notes/Documentation Is Training Data and It Sets the Recommendation Prior]] — public docs and usage examples decide whether an agent recommends a platform at all; DevRel's leverage in the agent era - [[3. Resources/Permanent Notes/Docs Co-Located With Source Outlast a Separate Handbook Page]] — an example in the DocBlock ships in the same commit as the function; a separate docs-site example never does - [[3. Resources/Permanent Notes/Adoption Gaps in Standards Are Usually Documentation Gaps]] — near-zero voluntary adoption among people who already have the skill points at the docs, not the difficulty - [[3. Resources/Permanent Notes/Unclear Setup Docs Force a Security Decision Onto the User]] — when docs don't say where a credential belongs, a security judgment the maintainer owed moves onto the reader - [[3. Resources/Permanent Notes/A Design System Needs a Human Steward Not Just a Repository]] — a repository of artifacts is not a system without an accountable human evolving the standards; Buley's design-system docs talk is the worked case - [[3. Resources/Readwise/Articles/Building Trust A Checklist for WordPress Plugin Developers|Building Trust: A Checklist for WordPress Plugin Developers]] — David McCan (WebTNG, 2026-09-19): docs, changelogs, and video walkthroughs as buyer-checked trust signals; 18-item checklist with the three verifiable WordPress.org mechanics (the "Tested up to" update without a version bump, GPL for the PHP portion, Patchstack registration) separated from the author's judgment calls on refunds and disclosure ## 📊 Measuring docs and choosing what to fix - [[3. Resources/Permanent Notes/A Docs Metric Earns Its Place by Naming Which Job It Does]] — a number either proves value upward or locates a page to fix; one that does neither is parked - [[3. Resources/Permanent Notes/A Documentation Gap Is Acceptable Only Once It Is a Recorded Decision]] — gaps are certain under capacity constraints; the control is a written decision per gap - [[3. Resources/Permanent Notes/Absence of Complaint Is Resignation Not Satisfaction]] — a quiet feedback channel measures distance from the docs; every new instrument raises complaint volume - [[3. Resources/Permanent Notes/A Navigation Redesign Is a Hypothesis Until Usability Data Confirms It]] — the WordPress Playground team's call for testing, applied to any docs IA change - [[3. Resources/Permanent Notes/Friction Logging Is the DevRel Equivalent of Code Review]] — walk the developer journey to find the failures before they cost you developers; the active remedy for silent channels - [[3. Resources/Permanent Notes/Documentation Restructure Decides Deduplication at Audit Not After]] — regroup first and deduplicate later forces rework; decide single-source-of-truth during the audit ## 🤖 Docs that agents read The cluster that grew fastest in 2026. Documentation is an input to models in three roles: training corpus, retrieved reference, and live instruction channel. - [[3. Resources/Permanent Notes/Any Text an Agent Reads Is a Control Surface]] — a model that can act doesn't distinguish a sentence describing a system from one instructing it; docs, error strings, readmes, and forum replies are all channels - [[3. Resources/Permanent Notes/AI-Facing Documentation Needs an Explicit Authority Boundary]] — a configured boundary that excludes speculative sources from the product's accepted behavior - [[3. Resources/Permanent Notes/AI Documentation Pipelines Need an Explicit Authority Source]] — the same rule from the producer side: a config-level statement of which sources count, or the pipeline presents unshipped work as shipped - [[3. Resources/Permanent Notes/Write Agent-Facing Docs Assuming the Agent Wont Fetch the Reference]] — put the critical instruction inline at the point of use; agents mid-task do not follow links out - [[3. Resources/Permanent Notes/Skill Descriptions Are Trigger Keywords Not Documentation]] — a description field is a search trigger loaded every turn; explanation belongs in the body - [[3. Resources/Permanent Notes/Documentation Prompts Are Documentation Assets Governed Like Code]] — prompts that generate docs get version control, review, ownership, and cross-repository testing ## 🏛️ Governing the docs function - [[3. Resources/Permanent Notes/Enforcing an SOP Beats Rewriting Documentation for Stopping Interruptions]] — when colleagues bypass the docs to ask you, the fix is manager buy-in and declining the out-of-process request, not another rewrite - [[3. Resources/Literature Notes/Milana Cap on WordCamp Belgrade, Documentation Tooling, and Open Source Sponsorship]] — WordPress documentation tooling and sponsorship from the team lead's side; origin of the authority-source claims above - [[3. Resources/Literature Notes/GitHub docs to WordPress with DocsPress]] — docs-as-code into WordPress via GitHub Actions; origin of the credential-placement claim - [[3. Resources/Literature Notes/Drupal AI Learners Club - Getting AI to Read Your Docs (Jurgen Haas)]] — MCP-served documentation and its token cost; origin of the dual-audience claim - [[Documentation Team Contributor Pathway]] — the WordPress Documentation Team on-ramp (handbooks, HelpHub, DevHub) from the WP Curriculum project; private project note, not published - [[3. Resources/Readwise/Articles/Is Dev Rel Marketing, Engineering, or Product The Answer Is Yes, Says Checkmarx's Tessa Mero|Is Dev Rel Marketing, Engineering, or Product? "The Answer Is Yes"]] — Tessa Mero (Checkmarx, HackerNoon interview, 2026-09-25): DevRel can report into marketing, engineering or product if the leader gives it latitude; a developer who can't start in a few minutes leaves; follower counts and impressions are vanity metrics unless tied to activation; "Copy Prompt" is replacing "Copy Code" as the docs snippet developers lift ## 📚 Books Full reviews in `4. Archives/Book reviews`, each with a Prompt-0 source map and a review synthesis. - [[Docs for Developers]] — Bhatti, Corleissen, Lambourne, Nunez, Waterhouse (2nd ed., 2026): the field guide; user research, friction logs, and measurement as an engineering discipline. Visual summary: [[Docs for Developers Visual.excalidraw|Docs for Developers Visual]] - [[Docs Like Code]] — Anne Gentle (2nd ed., 2017): the docs-as-code workflow that the DocsPress and repository-architecture material assumes - [[The Product is Docs]] — Christopher Gales and the Splunk documentation team (2nd ed., 2020): documentation as a product-development function, not a downstream service - [[Modern Technical Writing]] — Andrew Etter (2016): the short manifesto for lightweight markup, static sites, and writing less - [[Technical Writing for Software Developers]] — Chris Chinchilla (2024): the developer-as-writer angle, including AI drafting tools - [[Technical Writing for Engineers & Scientists]] — Finkelstein, Aune, Potter (2022): the academic textbook baseline the trade books react against ## 🎤 Events Session indexes for conferences on this topic. Each event map holds the talk-by-talk notes; this map holds the claims that outlived the event. - [[3. Resources/MOCs/Events/Write the Docs Berlin 2026 MOC]] — 15 recordings, 2026-09-22: docs metrics, capacity and repo architecture, AI and writer judgment, trust and security, career - [[3. Resources/MOCs/Events/Inclusive Design 24 2026 MOC]] — 22 recordings, 2026-09-24 and 25; Merrett on accessible documents, Savoy and Mathew on plain language, and Barros Pena on teaching the field are the documentation and education talks in the set - [[3. Resources/MOCs/Events/WordPress Accessibility Day 2025 MOC]] — 20 recordings, published 2026-09-08; Merrett on Office documents is the documentation talk - Pre-2026 conference notes (State of the Word 2022, WCUS 2023, OSSNA, LoopConf 2025, PressConf 2025) live in `4. Archives/Conferences`, which is not published; WordPress-specific events have their own maps under Events & Conferences in [[3. Resources/MOCs/MOCs]] ## 🔗 Related maps - [[3. Resources/MOCs/DevRel MOC]] — documentation is DevRel's largest surface; this map is listed there as an adjacent discipline - [[3. Resources/MOCs/AI Agent Safety MOC]] — the control-surface and authority-boundary claims from the agent side - [[3. Resources/MOCs/AI & the Future of Knowledge Work MOC]] — where the writer sits once generation is cheap - [[3. Resources/MOCs/Accessibility & Disability Inclusion MOC]] — accessible docs and the "accessibility for AI" framing Klepper argues against - [[3. Resources/MOCs/WordPress Platform Design MOC]] — DevHub, handbooks, and the Abilities API docs question - [[3. Resources/MOCs/Evidence & Claims Literacy MOC]] — the recurring pattern in docs talks: precise-sounding figures without method ## Open threads - Six Permanent candidates from the Write the Docs series are unwritten (listed in that map). Rayner's enforcement claim and Rubio's spec-in-CI claim belong in the governance and infrastructure sections here. - No Literature note yet ties the six book reviews together; a syntopical note on what the trade books agree on (docs-as-code, user research first, measure outcomes not pages) would let this map stop pointing at reviews one by one. ## Synthesis additions (2026-10-05 — docs agents read) - [[3. Resources/Readwise/Articles/How to Write a Research Paper All 8 Sections in the Right Order]] — Andy Stapleton (who sells courses) teaches writing a paper in dependency order, figures, results, methods, discussion, introduction, conclusion, then abstract and title, drawn from his own physical-sciences practice with no data on outcomes. - [[3. Resources/Readwise/Articles/Your RAG Pipeline Dies on Real Documents Here's Why]] — A HackerNoon piece (author inferred as Paolo Perrone) argues PDF parsers flatten tables and reading order silently, so RAG evals pass on clean documents; it features LlamaParse and its cost and accuracy multiples are LlamaIndex's own benchmark figures. - [[3. Resources/Permanent Notes/A RAG Parser That Drops Table Structure Fails Without Raising an Error]] — A PDF stores glyph positions, not tables, so a plain text extractor hands a RAG retriever flattened tables with no error and evals on clean documents keep passing. ## Synthesis additions (2026-10-07 — design systems built for agents) - [[3. Resources/Readwise/Articles/Design Systems in the Age of Agents What Changes, What Doesn't]] — In a Hatch Conference talk, Cassie of Unily describes building the Resin design system with agents as a third consumer, shipping context, skills and a human-written requirements record, while she says authorship of the knowledge and accountability for what ships stay human. ## Synthesis additions (2026-10-18 — registering previously unlisted notes) ### Permanent Notes - [[3. Resources/Permanent Notes/A Grammatically Correct Translation Can Silently Misrepresent Brand Meaning]] — A word-for-word translation can be grammatically flawless and still misrepresent an idiomatic brand phrase, and nothing looks broken enough for automated checks or non-native reviewers to catch it. Closest-fit placement. - [[3. Resources/Permanent Notes/A Style Rule Only Works If a Draft Can Be Checked Against It]] — A style or voice rule only improves output if a draft can pass or fail against it, so begin with a fact beats confident but warm. ### Literature Notes - [[3. Resources/Literature Notes/Google Took WPBeginner From 2.6M Clicks to 27K - Here's Why]] — Edward Sturm attributes WPBeginner's traffic collapse to promotional content on learn queries and long answer-burying posts, compounded by topic over-expansion. Closest-fit placement. - [[3. Resources/Literature Notes/How GravityKit Made AI Support Earn Its Place on the Front Line]] — GravityKit judged its AI support agent on whether it represents the company accurately, using adversarial tests, versioned releases, and documentation-server grounding. - [[3. Resources/Literature Notes/How To Rank In AI Overviews For Agency Clients]] — Ranking in AI Overviews rests on ordinary SEO foundations plus a page that offers what the summary can't, and agencies should measure citation, click, and outcome separately. Closest-fit placement. - [[3. Resources/Literature Notes/Stop Boosting Your Competitors Why Listicles Are Killing Your AI Search Visibility]] — Christopher Penn argues listicles that name competitors hurt AI search visibility, since models reward aggregate cross-source mentions over page-level authority. Closest-fit placement. - [[3. Resources/Literature Notes/The Reddit SEO Hack That Ranks Your Website Instead of Reddit]] — A video describes publishing short exact-phrase pages to rank for Reddit-style queries, a long-tail pattern that grows riskier when stacked with other tactics. Closest-fit placement. - [[3. Resources/Literature Notes/Why Publishing More Content Is Making Your SEO Worse]] — Argues publishing more content hurts SEO by diluting authority, so consolidating pages helps; the note says the claims lack data and cites no retrieval sources. Closest-fit placement.