The Doc Your Copilot Reads Is the Doc Your New Hire Reads
A new hire's first Monday is a stress test of your documentation, and it always has been. What changed is who else sits in the room. The paragraph that fails to explain token refresh to a person on day one now gets pasted into a coding assistant, and whatever that assistant builds from the paste turns up in a pull request before lunch. One document, two readers, and only one of them raises a hand when it does not understand.
The claim, in plain terms: a team does not need two sets of documentation, one for humans and one for machines, because what a model reader requires is what a busy human reader requires, enforced harder. Four writing habits survive a patient human and fail in front of a model. Fixing them costs an afternoon of editing, and the edited document is the same one a new hire can follow without the whiteboard session. A second doc, condensed for agents only, is the failed experiment we ran first, and it gets its section below.
Four habits humans forgive and models punish
The first habit is headings that mean nothing out of context. A section named "Notes" under "Authentication" may be about clock skew between the token server and the database, but the heading travels alone. A human reading top to bottom carries the context along; a model that retrieves one paragraph, or quotes one paragraph at you in a chat, has only what the paragraph itself declares. Write every heading as if the reader arrives by helicopter: "Clock skew between the token server and the database" works at any altitude, "Notes" does not.
The second habit is pointing at the page instead of the address. "As mentioned above", "in the previous section", "the latter": all three assume a linear reader with a working memory. The quoting reader holds nothing. The skimming human, who is also reading your document, gave up scrolling back three paragraphs ago. Reference by name and location, every time: the section title, the anchor, the URL. The rule costs a few words and buys a document that survives being read in pieces, which is how both audiences actually read it.
The third habit is capability without a default. "The refresh window is configurable" is true and useless, because the next reader, human or model, has to invent a number, and invents a confident one. State the default on the same line as the setting, plus the one condition under which you would change it. A default written next to its setting stays findable the day someone must decide whether the default is the problem.
The fourth habit is pointing at another document for the very thing the reader needed. "If refresh fails, see the auth guide" sends the reader to a guide that says the same sentence back. Models follow circles as patiently as people do, and neither one finds an answer at the end of the loop. Settle the circular reference on the page the reader is standing on, and let cross-links carry depth rather than carry the answer.
Give every section an address, then stop moving it
A heading, once published, is an address, and the promise is that this address does not move. Both readers take you at the promise. The new hire writes section titles into her notes during week one, and the assistant keeps them as the labels it will quote back to you for months. Rename a heading and you break something with no error message: the runbook that says the token-lifecycle section explains the retry budget, the issue comment that links to #token-lifecycle, the assistant answer built on the old wording. The 2 a.m. version of this failure is mechanical: a search for "lifecycle" now returns a 2023 blog post, and that is what the on-call engineer reads.
Renaming is therefore a migration, and migrations get checklists. Every cross-reference updates in the same commit, every external link you can find is redirected, and the old heading text should appear once, in the new section, spelled out for the readers and the retrievers who still hold the old address. The human parallel is exact: a team's internal notes and private links rot the day the headings churn. A heading you keep is infrastructure. A heading you rename without a checklist is a broken link nobody has told you about yet.
One meaning per word
Inside one repository, every concept gets one name. If a session and a token are different things, one sentence says so exactly once: "A session holds one or more tokens, and a refresh token outlives its access token." From then on, those words mean only that. The runbook's "credential" and the onboarding guide's "credential" name the same object, or the difference is written down, because the assistant that joins your documents across repositories has no way to guess whether the vocabulary shifted between the two.
Where history forces two names onto one thing, declare the alias instead of hiding it: "The migration guide calls this object a ticket. They are the same thing, renamed in 2025." One honest sentence beats a glossary nobody opens. The test for any paragraph is the quote test: copy the paragraph, alone, into a chat with someone who has not read the surrounding page, and ask whether it still means exactly one thing. If it survives, the model reading your repository survives it too. If it does not, the failure you just fixed for the machine is the same one that used to cost you an hour of onboarding.
Examples that bring their own expected output
An example is not finished until it states what success prints. The contrast below is a before-and-after we keep pinned to the wall, condensed from one runbook edit:
## Gotchas
Auth: see above. If refresh stops working, ask in #platform.
## Token refresh, and when a request uses the old token
The client refreshes a token when it is within 60 seconds of expiry.
A request already in flight keeps using the old token, which stays
valid for 5 minutes after the refresh.
Default: 60 s. Change it only if an idle connection is dropped by
your load balancer sooner than the 60 s window.
The second section can be quoted anywhere on earth and still teaches. It has an address, a fixed behavior, a default, and the condition for changing the default. It also carries its own test: run the procedure, compare the output, and the documentation either matches the system or files a bug. An example wired into CI rots into a red build instead of into a wrong answer handed to a reader, human or model, and that difference is why the good version above is written the way it is. An example without its expected output asks the reader to supply the answer. With it, the example can be checked, rerun, and graded.
The two-copy experiment we retired
Here is the regret, as promised. We wrote the condensed agent copy: a shorter, imperative-flavored version of an architecture document, stripped of narrative, tuned for retrieval. For two weeks it looked like the future. Then the source document changed its refresh window and the condensed copy kept the old number, because a summary has no CI. The page that disagreed with the system was exactly the one an assistant quoted, with the stale figure, in a code review, and the fix was deleting the copy rather than adding a sync job. One source of truth, enforced by the same CI as the code, won on maintenance alone.
The edits that survived the deletion were small and mechanical: headings that travel, defaults on the line, aliases declared, examples with outputs. What changed for the humans was quieter. The whiteboard photo stopped being the only copy of the token-refresh behavior, because the behavior now exists, checkable, in the runbook. New-hire questions moved from "where is this written" to "why is it written this way", which is the conversation worth having on day one. Nobody measured the minutes saved, and we will not invent numbers here: the observable change is which questions get asked.
What a precise document still cannot do
A precise document makes an assistant's answer traceable, not correct. Retrieval can still bring back the wrong paragraph; a model can still misread a sentence you would call unambiguous; and neither failure announces itself. The workaround is the same for both readers, and it is why anchors matter more than prose polish: either a wrong answer can be checked against its home paragraph in one click, or it cannot, and you designed that difference. Intent stays outside the document entirely. "Should we refresh proactively or let requests fail over" is not syntax, the model will not ask you which you meant, and neither will the new hire on day one. That question is what the first meeting with a person is for. The document's job is to make everything before that question unnecessary, so the meeting starts at the part only a human can answer.
The takeaway fits on one line, applied to the paragraph open in your editor: does every heading travel, does every reference point at an address, does every configurable carry its default on the line, does every example print what success looks like. Fix those four and you are done, because you will have written one document both readers can follow. Skip the second copy. We already wrote it for you, and then we deleted it.
AngoraTek writes documentation as part of delivery, on the theory that the same page should serve the new hire and the tools that read it. If there is a section your team keeps re-explaining, bring us that section and we will make it travel.Thanks for reading this far. If this sounds like the problem you're wrestling with, tell us about it. The team reads every message.
Start a conversation