documentation-standards

name	documentation-standards
description	Standards and guidelines for organizing, structuring, and maintaining documentation in the PRPM repository - ensures consistency across user docs, development docs, and internal references

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

1. ✅ Move file to correct location
2. ✅ Update all references to moved file
3. ✅ Update README.md links if needed
4. ✅ Update .gitignore if needed
5. ✅ Test that all links work
6. ✅ 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