Documentation Manager
Scannednpx machina-cli add skill crypdick/pynchy/docs-manager --openclawDocumentation 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
Source
git clone https://github.com/crypdick/pynchy/blob/main/.claude/skills/docs-manager/SKILL.mdView on GitHub Overview
Documentation Manager guides where to document in Pynchy, helping maintain consistency and fix broken links. It codifies information architecture, a writing philosophy, and tree-shaped navigation, covering doc-code coupling, no hard-coded usernames, and extensibility for pluggable subsystems.
How This Skill Works
Internally, it uses a quick decision tree to route content to the correct docs file (architecture topics, install guide, or subsystem pages). It enforces the style rules (Google Style, present tense, active voice) and checks for a single source of truth, cross-links, and broken links via pre-commit hooks and mkdocs build.
When to Use It
- Adding a new feature and deciding the right docs location (architecture, install, or subsystems)
- Documenting security implications
- Reflecting a development workflow change
- Bug fix that requires installation or doc updates
- Refactoring with user-visible impact (update relevant docs)
Quick Start
- Step 1: Use the quick decision tree to choose the right docs location.
- Step 2: Add or update the topic file with a single source of truth and links.
- Step 3: Run uv run mkdocs build --strict to validate links and navigation.
Best Practices
- Follow the Google Style Guide: write in present tense and active voice; no 'we' or 'they'.
- Place content using the decision tree to ensure the correct file and navigation.
- Maintain a single source of truth with precise cross-links rather than duplicates.
- Keep files small and topic-focused; one topic per file.
- Validate changes with link checks and mkdocs build before committing.
Example Use Cases
- Created docs/architecture/index.md and linked new architecture topic when adding a feature.
- Documented a security implication in docs/architecture/security.md.
- Updated docs/install.md to reflect a new installation requirement.
- Updated a docs/architecture topic after a user-visible refactor.
- Fixed a broken link in a topic and refreshed the navigation in mkdocs.yml.
