# Docs Co-Located With Source Outlast a Separate Handbook Page ## Claim A code example authored inside the DocBlock of the function it documents stays synced with that function because it ships in the same commit, which a separate documentation-site example never does. <!-- atomicity: 1 idea ✓ --> ## Scope & conditions - The mechanism is the shared commit, not proximity — an example in the same repository but a different file gets no guarantee. - Reviewers see the example diff alongside the behaviour change, which is where the correction actually happens. - Costs expressiveness: a DocBlock cannot hold a long narrative tutorial, so the handbook page still has a job. - Applies to any docs-as-code arrangement, and explains why generated API references age better than hand-written guides. ## Evidence From the WordPress announcement that runnable code examples are live in the Code Reference, authored in function DocBlocks. ## Links - [[Write Agent-Facing Docs Assuming the Agent Wont Fetch the Reference]] — the same argument for co-location, made for an agent reader rather than a human one - [[A Format Whose Source Is Its Presentation Cannot Hide Bloat]] — the same preference for a substrate where drift is visible - [[3. Resources/MOCs/WordPress Platform Design MOC]] — the platform-design thread on documentation durability. - [[3. Resources/MOCs/Documentation & Technical Writing MOC]] — applies-in: the docs discipline map, infrastructure cluster - [[3. Resources/Permanent Notes/Agent-Facing Docs Are a Build Artifact With a Pipeline and Tests]] — applied in: a skill file, markdown mirror or llms.txt is generated output and needs a build, version and tests (Whinnery).