Documentation Manager · diff
git:20260906.fc7338b to git:20260906.705c516
4 added, 53 removed. Audit A to A.
---
name: Documentation Manager
description: Use when writing or reviewing pynchy documentation, deciding where to document things, updating the docs, checking doc consistency, or fixing broken links. Covers information architecture, writing philosophy, tree-shaped navigation, doc-code coupling, no hard-coded usernames, extensibility framing for pluggable subsystems, and when to add code comments.
---
# Documentation Manager
Helps decide where to document things and maintain consistency across Pynchy docs.
- ## Style Guide
-
- - Write for a **user trying to achieve a goal**. Don't chronicle the evolution of the codebase. Don't go into unnecessary technical details that are not relevant to the user's goal.
- - Follow the [Google Style Guide](https://developers.google.com/style). Write in the present tense. Don't use "we" or "they". Write in the active voice. Don't use "is" or "are".
- - Read `docs/contributing/contributing-docs.md` for the full documentation philosophy and information architecture rules.
-
- ## Where to Document What
-
- Quick decision tree:
-
- **New feature?**
- - Architecture decision → `docs/architecture/` (find the relevant topic file, or create a new one)
- - Installation requirement → `docs/installation/index.md`
- - Security implication → `docs/architecture/security.md`
- - Development workflow change → `.claude/skills/pynchy-dev/SKILL.md`
-
- **Bug fix?**
- - If it needs install change → `docs/installation/index.md`
- - Usually: No doc update needed
-
- **Refactoring?**
- - If user-visible → Update relevant docs
- - If internal only → No doc update
-
- ## File Purposes
-
- | File | What Goes There |
- |------|-----------------|
- | `README.md` | Philosophy, quick start, high-level overview |
- | `docs/installation/index.md` | Complete installation guide |
- | `docs/architecture/security.md` | Security model, threat analysis |
- | `docs/architecture/index.md` | Architecture overview and links to topic pages |
- | `docs/architecture/*.md` | One topic per file (containers, routing, tasks, etc.) |
- | `.claude/skills/` | Development context skills for Claude Code agents |
-
- ## Information Architecture Rules
+ ## Documentation policy
- 1. **Single source of truth** — Every concept explained in exactly one place. Cross-link, don't duplicate.
- 2. **Tree-shaped navigation** — Root files have links + short summaries. Leaf files have the actual content.
- 3. **Small, focused files** — One topic per file. If it covers multiple concerns, split it.
+ Read [the contributing style guide](../../../docs/contributing/contributing-docs.md)
+ for audience, placement, style, and information architecture. Keep those rules there;
+ this skill owns the verification procedure.
## Validation
**Before committing:**
```bash
# Check for broken links
uv run mkdocs build --strict
```
**After moving/renaming files:**
1. Search for all references to old name
2. Update each reference
3. Update `mkdocs.yml` nav
4. Test with `uv run mkdocs build --strict`
-
- ## Common Mistakes
-
- - Duplicating content across files (link instead)
- - Chronological explanations ("First we tried X...")
- - Mixing audiences (keep README brief, details in docs/)
- - Forgetting to update references after renames
- - Writing mega-files that cover multiple topics
-
- ## Link Checking
-
- Link validation runs automatically in prek hooks. If docs have broken links, the commit will fail.
-
- To manually check: `uv run mkdocs build --strict`