Documentation Repository
Adapts contribution guidance for prose, links, examples, accessibility, and documentation build checks.
Scenario
You maintain a repository dedicated primarily to technical documentation.
The repository contains:
- tutorials;
- conceptual guides;
- API examples;
- troubleshooting pages;
- navigation metadata.
Documentation quality depends on more than grammar.
Agents must preserve:
- technical accuracy;
- links;
- code examples;
- navigation;
- terminology consistency.
Repository Structure
docs/
├── content/
│ ├── getting-started/
│ ├── guides/
│ ├── concepts/
│ └── troubleshooting/
├── examples/
├── navigation.ts
├── scripts/
│ └── validate-links.ts
├── package.json
└── AGENTS.md
AGENTS.md
# Documentation Instructions
## Content
- Preserve technical meaning when editing prose.
- Follow the repository's existing terminology and product naming.
- Prefer clear, task-oriented explanations over unnecessary jargon.
- Do not invent product behavior that is not supported by the repository or source documentation.
## Code Examples
- Keep code examples consistent with the documented API.
- Prefer existing example patterns.
- Update related examples when a public API change makes them outdated.
- Do not include real secrets or credentials.
## Structure
- Follow existing heading conventions.
- Preserve stable links and anchors when practical.
- Update navigation metadata when adding or moving pages.
## Links
- Use the repository's established internal-link format.
- Check affected internal links when pages are renamed or moved.
- Avoid leaving references to deleted pages.
## Validation
After documentation changes:
- run `pnpm lint`;
- run documentation validation;
- run link checking when links or page structure change;
- run the documentation build for structural changes.
What This Does
This treats documentation as a product rather than miscellaneous Markdown files.
For example, renaming:
content/guides/authentication.md
may affect:
navigation
internal links
external links
search indexing
bookmarks
The change therefore involves more than moving a file.
Code examples also deserve validation.
A documentation page containing:
client.users.create({
email: "user@example.com",
});
becomes misleading if the actual API now requires:
client.users.create({
email: "user@example.com",
name: "Alex",
});
What This Does NOT Do
The instructions do not require preserving bad documentation merely because it already exists.
Improving:
clarity
structure
examples
terminology
is appropriate.
The goal is to preserve technical correctness and repository conventions while making improvements.
The file also does not require every wording change to run the entire documentation toolchain.
Validation should match the change.
Why These Instructions Matter
Documentation changes can break user workflows even when no application code changes.
Suppose an agent moves:
/guides/deployment
to:
/deployment/guide
without updating links.
The page itself may look correct, while dozens of references now return 404 errors.
Navigation metadata can have similar effects.
A new page may exist in the repository but remain impossible to discover through the documentation UI.
Key Decisions
Technical accuracy comes first
A beautifully written example that describes nonexistent behavior is still bad documentation.
Treat code examples as code
Examples should track the real API and should be validated where tooling allows.
Preserve navigation intentionally
Moving pages affects more than directory organization.
Match validation to the edit
A typo fix may need little validation.
A navigation restructure should run link and build checks.
Keep terminology consistent
If the product calls something a:
workspace
documentation should not randomly alternate between:
workspace
project
organization
tenant
unless those concepts are actually distinct.
When to Use This Pattern
Use this pattern when:
- documentation is maintained as code;
- docs contain runnable examples;
- navigation is repository-driven;
- links and anchors matter;
- agents contribute technical writing.
A documentation repository needs instructions just as much as an application repository—it simply protects different invariants.