PRPM Documentation Standards
Documentation Organization
Internal Documentation (development/docs/)
Purpose: Documentation for developers working on PRPM itself
Files:
- - GitHub Actions workflows reference
- - NPM package publishing process and order
- - Development setup, environment, and workflows
- - 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: (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
Files:
- - Project overview, quick start, installation
- - Contribution guidelines
- - Version history and changes
- - License information
- - Project roadmap and future plans
Audience: Everyone (first impression)
Claude Skills (.claude/skills/)
Purpose: Knowledge base and reference materials for AI assistants
Files:
postgres-migrations-skill.md
pulumi-troubleshooting-skill.md
- - How to create new skills
documentation-standards.md
Subdirectories:
- - PRPM-specific development knowledge
- - Self-improvement patterns
- - 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
markdown
# Title
Brief description (1-2 sentences)
## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)
## Section 1
Content...
### Subsection 1.1
Details...
## Examples
\`\`\`bash
# Example command
prpm install @username/package-name
\`\`\`
## See Also
- [Related Doc](./related.md)
Cross-References
- Use relative paths for links
- Keep links within same category when possible
- Update links when moving files
Internal → Internal:
markdown
See [Publishing Guide](./PUBLISHING.md)
Internal → User:
markdown
See [User Guide](../../docs/user-guide.md)
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
- Update internal docs in 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 | | Contributors | CI/CD, publishing |
| User-Facing | | Users | Guides, tutorials |
| Project Root | | Everyone | README, LICENSE |
| AI Skills | | AI assistants | Troubleshooting |
| Package Docs | | Package users | API reference |
Tools
Documentation Generators
- TypeDoc - For TypeScript API docs (future)
- VitePress or Docusaurus - For docs/ site (future)
Linting
bash
# Check markdown
markdownlint docs/
# Check links
markdown-link-check docs/**/*.md
Building Docs Site (Future)
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