documentation-standards

Original：🇺🇸 English
Translated

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

8installs
Sourcepr-pm/prpm
Added on

NPX Install

npx skill4agent add pr-pm/prpm documentation-standards

Tags

Translated version includes tags in frontmatter
documentation-standardsprpm-repositorydoc-organizationmarkdown-guidanceai-assistant-docs

SKILL.md Content

View Translation Comparison →

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

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:
  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 TypeLocationAudienceExamples
Internal Dev
development/docs/
ContributorsCI/CD, publishing
User-Facing
docs/
UsersGuides, tutorials
Project Root
/
EveryoneREADME, LICENSE
AI Skills
.claude/skills/
AI assistantsTroubleshooting
Package Docs
packages/*/README.md
Package usersAPI 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)

bash
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