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. 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.mdfor 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/install.md - Security implication →
docs/architecture/security.md - Development workflow change →
.claude/skills/pynchy-dev/SKILL.md
Bug fix?
- If it needs install change →
docs/install.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/install.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
- Single source of truth — Every concept explained in exactly one place. Cross-link, don't duplicate.
- Tree-shaped navigation — Root files have links + short summaries. Leaf files have the actual content.
- Small, focused files — One topic per file. If it covers multiple concerns, split it.
Validation
Before committing:
# Check for broken links
uv run mkdocs build --strict
After moving/renaming files:
- Search for all references to old name
- Update each reference
- Update
mkdocs.ymlnav - 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 pre-commit hooks. If docs have broken links, the commit will fail.
To manually check: uv run mkdocs build --strict