--- type: "article" title: "Agent Ready Docs - 5 Lessons Learned" newsletter: "Joyce Stack" newsletter_handle: "joycestack" newsletter_url: "https://work.joycestack.com/" author: "Joyce Stack (@joycestack)" published: "2026-03-21T12:20:50.000Z" canonical_url: "https://work.joycestack.com/a/agent-ready-docs-5-lessons-learned" markdown_url: "https://work.joycestack.com/a/agent-ready-docs-5-lessons-learned.md" chat_url: "https://work.joycestack.com/a/agent-ready-docs-5-lessons-learned/chat" source_url: "https://preview.mailerlite.io/preview/2117849/emails/182389557377893598" body_source: "native" likes: 2 replies: 3 body_words: 926 --- # Agent Ready Docs - 5 Lessons Learned March 2026 # Midlife in Motion Notes from someone running experiments on work, health and what comes next. THIS WEEK'S EXPERIMENT # **Agent Ready Docs - 5 Lessons Learned** I've been deep diving into what makes documentation 'agent ready'. Here are 5 patterns I keep seeing, and what they mean for how you should write. ## 1. Vague Documentation vs. Missing Documentation If an agent has no information, it admits uncertainty. If documentation is vague, the agent fills the gaps with training data and produces confident but wrong answers. ### Example: Commit Messages One CONTRIBUTING file that I came across had a link to [Erlangs write a good commit message](https://github.com/erlang/otp/wiki/writing-good-commit-messages) This gives an agent just enough signal to invent [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). If this is your standard then great, if it is not then agents will make it up. In this case, not having a CONTRIBUTING file is safer as the agent will respond with honestly and tell you that it doesn’t know. ### Try it yourself Open a repository with a vague CONTRIBUTING in Copilot Chat and ask: ``` What commit message format should I use in this repository? ``` If the answer is specific and confident — Conventional Commits but none of that is written in your docs, you just watched a hallucination happen in real time. ## 2. Good Structure ≠ Usability A repo can score high on AI readiness (e.g. good structure) and fail an agent ready integration test. Well-formed Markdown with missing information is still unusable. ### Example: Project Setup If your project depends on files existing and passing tests but your CONTRIBUTING never explains how to run tests or start the service, the agent passes the “good structure” health check but cannot actually contribute. ### Try it yourself Open a repository and type into Copilot Chat: *Give me the exact commands to set up this project locally and run the tests.* *Do not infer anything from the tech stack.* *Only use what is written in the documentation.* Watch where it stops. Every gap it cannot fill without guessing is a documentation debt that your AI Readiness score never caught. ## 3. Placement Matters as Much as Content Information in the wrong file might as well be absent. Documentation must be connected, not just present. ### Example: Linting Rules A CONTRIBUTING said ensure code is linted to appropriate standards The AGENTS.md contained: ``` Run vale and markdownlint --disable MD013 before committing Vale configuration is in .vale.ini markdownlint configuration is in .markdownlint.json ``` The agent reads CONTRIBUTING. It finds "ensure code is linted to appropriate standards." There is no link to AGENTS.md. The agent has no reason to look there. It needs to answer: what linting tools should I run? It knows it is in a documentation repository. It knows common documentation linting tools. It answers from training data: run markdownlint, perhaps vale. It may get the tools right by luck. It will not know about --disable MD013. It will not know where the config files are. It will not flag the .vale.ini location. The rules exist. The agent cannot see them. Not because they are hidden because nothing connected them. ### Try it yourself Find a repository where AGENTS.md exists but CONTRIBUTING never references it. *I want to raise a pull request. Walk me through every convention and check I need to follow before I open it.* Count how many rules from AGENTS.md appear in the answer. The ones that don't are invisible — not because they don't exist, but because nothing connected them. ## 4. A single unclosed code fence can break document parsing Markdown parsers treat everything after an **unclosed fenced code block** as part of the code block. Example: ```` ```yaml task: summarize agent: summary_writer ```` If the closing fence is missing, the rest of the document is interpreted as code rather than prose. Agents may lose the document structure entirely, causing headings, sections, and instructions to become invisible. ### Try it yourself Deliberately introduce an unclosed code fence somewhere in a document, then ask the agent a question that requires it to read content *after* the unclosed fence. ``` What are the contribution guidelines for this project? ``` If the agent can't answer questions about sections that appear after the unclosed fence — or treats prose as code — the test fails. The agent has lost the document structure. ## 5. The Standard Covers Structure. It Doesn't Cover Content Our Docs as Code standard tells teams which files to create - a README and a CONTRIBUTING. It does not tell them what those files need to contain for an AI agent to use them safely. A README exists but has no problem statement. A CONTRIBUTING file exists but defines no scope boundaries. An agent reads both, finds no constraints, and starts proposing changes - confidently, and incorrectly. The files are present. The standard is satisfied. The agent is still guessing. Presence is not the same as usability. What each file should contain - a problem statement, a named audience, scope boundaries, safe-change rules - is a different requirement from whether it exists at all. And nobody has written that requirement down yet but I am working on it. ## Final Takeaways I now see documentation as AI infrastructure. Without clear, structured, and maintained documentation, AI systems cannot operate reliably, safely, or at scale. Documentation debt doesn't disappear when you adopt AI. It compounds. The documentation your agents read is an engineering asset. Start treating it like one. Glad you're here. Forward it to someone who'd get it. Unsubscribe *** ## Discussion (3 replies) Numbering shows the reply tree: `2.1` is a reply to `2`. Message text is reproduced verbatim as posted. ### 1. Joyce Stack (@joycestack) - 2026-03-21T12:23:39.321Z Another blog post, another different blog post style. Thanks for your patience. Here are a few things I've learned in recent weeks with trying to understand agent friendly docs. ### 2. Mark Boyd (@markboyd) - 2026-03-21T12:35:22.727Z I think there is good reason for the different styles. I like this style for introducing new tech concepts, especially the try it yourself format and lines like "you just saw a hallucination in real time" is kind of exciting to play along. ### 3. Joyce Stack (@joycestack) - 2026-03-21T12:43:53.409Z > Quoting Mark Boyd (@markboyd): I think there is good reason for the different styles. I like this style for introducing new tech concepts, especially the try it yourself format and lines like "you just saw a hallucination in real t… Thanks Mark. Playing around a with newsletter style, formats and MailerLite before I start sending to peoples inbox. Spacing and fonts feel a little all over the place just yet. Thanks for reading.