PRPM Documentation Standards
Documentation Organization
Internal Documentation (development/docs/)
Purpose: Documentation for developers working on PRPM itself
Location: development/docs/
Files:
-
GITHUB_WORKFLOWS.md
-
GitHub Actions workflows reference
-
PUBLISHING.md
-
NPM package publishing process and order
-
DEVELOPMENT.md
-
Development setup, environment, and workflows
-
DOCKER.md
-
Docker setup, services, and troubleshooting
Audience: PRPM contributors, maintainers, CI/CD systems
User-Facing Documentation (docs/)
Purpose: Documentation for PRPM users and package authors
Location: docs/ (at project root)
Files:
-
User guides
-
API documentation
-
Package authoring guides
-
CLI command reference
-
Examples and tutorials
Audience: PRPM end users, package authors, integrators
Project-Level Documentation (root)
Purpose: Standard project files that belong at repository root
Location: Project root /
Files:
-
README.md
-
Project overview, quick start, installation
-
CONTRIBUTING.md
-
Contribution guidelines
-
CHANGELOG.md
-
Version history and changes
-
LICENSE
-
License information
-
ROADMAP.md
-
Project roadmap and future plans
Audience: Everyone (first impression)
Claude Skills (.claude/skills/)
Purpose: Knowledge base and reference materials for AI assistants
Location: .claude/skills/
Files:
-
postgres-migrations-skill.md
-
PostgreSQL migrations guidance
-
pulumi-troubleshooting-skill.md
-
Pulumi troubleshooting
-
NEW_SKILLS.md
-
How to create new skills
-
documentation-standards.md
-
This file
Subdirectories:
-
prpm-development/
-
PRPM-specific development knowledge
-
self-improving/
-
Self-improvement patterns
-
thoroughness/
-
Thoroughness and quality guidelines
Audience: AI assistants (Claude, etc.)
Rules for Documentation Placement
When to use development/docs/
✅ GitHub Actions workflows and CI/CD ✅ Internal build/release processes ✅ Development environment setup ✅ Architecture decision records ✅ Internal troubleshooting guides ✅ Database schema documentation ✅ Infrastructure documentation
❌ User-facing tutorials ❌ CLI usage guides ❌ API reference for end users
When to use docs/
✅ User guides and tutorials ✅ CLI command reference ✅ Package authoring guides ✅ API documentation for users ✅ Integration examples ✅ FAQ for users
❌ Internal development workflows ❌ CI/CD documentation ❌ Build/release processes
When to use .claude/skills/
✅ Specialized knowledge for AI assistants ✅ Domain-specific best practices ✅ Troubleshooting patterns ✅ Code review guidelines ✅ Project-specific conventions
❌ General documentation ❌ User guides ❌ API references
Documentation Standards
Markdown Files
-
Use clear, descriptive filenames (kebab-case)
-
Include table of contents for docs > 200 lines
-
Use proper heading hierarchy (# → ## → ###)
-
Include code examples with syntax highlighting
-
Add frontmatter if using a static site generator
Example Structure
Title
Brief description (1-2 sentences)
Table of Contents
Section 1
Content...
Subsection 1.1
Details...
Examples
```bash
Example command
prpm install @username/package-name ```
See Also
Cross-References
-
Use relative paths for links
-
Keep links within same category when possible
-
Update links when moving files
Internal → Internal:
See Publishing Guide
Internal → User:
See User Guide
Migration Checklist
When reorganizing documentation:
-
✅ Move file to correct location
-
✅ Update all references to moved file
-
✅ Update README.md links if needed
-
✅ Update .gitignore if needed
-
✅ Test that all links work
-
✅ Commit with clear message explaining move
Package-Specific Documentation
Each package should have its own README:
packages/ ├── cli/ │ └── README.md # CLI package overview ├── registry/ │ └── README.md # Registry server docs ├── registry-client/ │ └── README.md # Client library docs ├── types/ │ └── README.md # Type definitions docs └── webapp/ └── README.md # WebApp docs
Maintenance
Regular Reviews
-
Quarterly review of docs/ for accuracy
-
Remove outdated documentation
-
Update examples to use latest version
-
Check for broken links
When Adding Features
-
Update relevant user docs in docs/
-
Update internal docs in development/docs/ if needed
-
Add examples
-
Update CHANGELOG.md
When Deprecating Features
-
Add deprecation notice to docs
-
Provide migration guide
-
Keep docs until feature is removed
-
Update CHANGELOG.md
Quick Reference
Documentation Type Location Audience Examples
Internal Dev development/docs/
Contributors CI/CD, publishing
User-Facing docs/
Users Guides, tutorials
Project Root /
Everyone README, LICENSE
AI Skills .claude/skills/
AI assistants Troubleshooting
Package Docs packages/*/README.md
Package users API reference
Tools
Documentation Generators
-
TypeDoc - For TypeScript API docs (future)
-
VitePress or Docusaurus - For docs/ site (future)
Linting
Check markdown
markdownlint docs/
Check links
markdown-link-check docs/**/*.md
Building Docs Site (Future)
cd docs/ npm run build
Examples
Good Documentation Structure
prpm/ ├── README.md # Project overview ├── CONTRIBUTING.md # How to contribute ├── CHANGELOG.md # Version history ├── ROADMAP.md # Future plans ├── development/ │ └── docs/ │ ├── GITHUB_WORKFLOWS.md # CI/CD reference │ ├── PUBLISHING.md # Release process │ ├── DEVELOPMENT.md # Dev setup │ └── DOCKER.md # Services setup ├── docs/ │ ├── getting-started.md # User onboarding │ ├── cli-reference.md # Command reference │ ├── package-authoring.md # Creating packages │ └── api/ │ └── registry-client.md # API docs └── .claude/ └── skills/ ├── documentation-standards.md ├── postgres-migrations-skill.md └── pulumi-troubleshooting-skill.md
Bad Documentation Structure ❌
prpm/ ├── README.md ├── WORKFLOWS.md # Should be in development/docs/ ├── USER_GUIDE.md # Should be in docs/ ├── dev-setup.md # Should be in development/docs/ └── troubleshooting.md # Unclear audience/location
Version
Last Updated: 2025-10-21 Applies To: PRPM v2+ Review Date: 2026-01-21