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](#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:

See [Publishing Guide](./PUBLISHING.md)

Internal → User:

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 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

documentation-standards

PRPM Documentation Standards

Documentation Organization

Internal Documentation (development/docs/)