Back to Details

documentation-standards

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PRPM Documentation Standards

PRPM 文档标准

Documentation Organization

文档组织方式

Internal Documentation (development/docs/)

内部文档（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
用途： 供PRPM内部开发人员使用的文档
存放位置： 
development/docs/
文件列表：
  • GITHUB_WORKFLOWS.md
    - GitHub Actions 工作流参考
  • PUBLISHING.md
    - NPM包发布流程与顺序说明
  • DEVELOPMENT.md
    - 开发环境搭建、配置及工作流说明
  • DOCKER.md
    - Docker环境搭建、服务配置及故障排查指南
受众： PRPM贡献者、维护人员、CI/CD系统

User-Facing Documentation (docs/)

用户面向文档（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
用途： 供PRPM终端用户和包开发者使用的文档
存放位置： 
docs/
（项目根目录下）
文件列表：
  • 用户指南
  • API文档
  • 包开发指南
  • CLI命令参考手册
  • 示例与教程
受众： PRPM终端用户、包开发者、集成人员

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)
用途： 存放在仓库根目录的标准项目文件
存放位置： 项目根目录 
/
文件列表：
  • README.md
    - 项目概述、快速开始、安装说明
  • CONTRIBUTING.md
    - 贡献指南
  • CHANGELOG.md
    - 版本历史与更新记录
  • LICENSE
    - 许可证信息
  • ROADMAP.md
    - 项目路线图与未来规划
受众： 所有访问仓库的人员（第一印象资料）

Claude Skills (.claude/skills/)

Claude 技能文档（.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.)
用途： 供AI助手使用的知识库与参考资料
存放位置： 
.claude/skills/
文件列表：
  • postgres-migrations-skill.md
    - PostgreSQL 迁移操作指南
  • pulumi-troubleshooting-skill.md
    - Pulumi 故障排查指南
  • NEW_SKILLS.md
    - 新技能创建方法
  • documentation-standards.md
    - 本文档
子目录：
  • prpm-development/
    - PRPM专属开发知识
  • self-improving/
    - 自我优化模式
  • thoroughness/
    - 严谨性与质量规范
受众： AI助手（如Claude等）

Rules for Documentation Placement

文档存放规则

When to use development/docs/

何时使用 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
✅ GitHub Actions 工作流与CI/CD相关内容 ✅ 内部构建/发布流程 ✅ 开发环境搭建 ✅ 架构决策记录 ✅ 内部故障排查指南 ✅ 数据库架构文档 ✅ 基础设施文档
❌ 用户面向教程 ❌ CLI使用指南 ❌ 面向终端用户的API参考

When to use docs/

何时使用 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
✅ 用户指南与教程 ✅ CLI命令参考手册 ✅ 包开发指南 ✅ 面向用户的API文档 ✅ 集成示例 ✅ 用户常见问题（FAQ）
❌ 内部开发工作流 ❌ CI/CD文档 ❌ 构建/发布流程

When to use .claude/skills/

何时使用 .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
✅ 供AI助手使用的专业知识 ✅ 领域特定最佳实践 ✅ 故障排查模式 ✅ 代码审查规范 ✅ 项目特定约定
❌ 通用文档 ❌ 用户指南 ❌ API参考资料

Documentation Standards

文档标准

Markdown Files

Markdown 文件规范

  • 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
  • 使用清晰、描述性的文件名（短横线分隔命名法 kebab-case）
  • 超过200行的文档需包含目录
  • 使用正确的标题层级（# → ## → ###）
  • 包含带语法高亮的代码示例
  • 若使用静态站点生成器，需添加前置元数据

Example Structure

示例结构

markdown
undefined
markdown
undefined

Title

标题

Brief description (1-2 sentences)
简短描述（1-2句话）

Table of Contents

目录

Section 1

章节1

Content...
内容...

Subsection 1.1

子章节1.1

Details...
详细内容...

Examples

示例

```bash
bash
undefined

Example command

示例命令

prpm install @username/package-name ```
prpm install @username/package-name
undefined

See Also

相关链接

  • Related Doc
undefined
  • 相关文档
undefined

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)
  • 使用相对路径作为链接
  • 尽可能保持链接在同一分类下
  • 移动文件时更新所有相关链接
内部→内部：
markdown
查看 [发布指南](./PUBLISHING.md)
内部→用户：
markdown
查看 [用户指南](../../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
重新组织文档时需完成：
  1. ✅ 将文件移动至正确位置
  2. ✅ 更新所有指向该文件的引用
  3. ✅ 若需要，更新README.md中的链接
  4. ✅ 若需要，更新.gitignore
  5. ✅ 测试所有链接是否可用
  6. ✅ 提交时使用清晰的说明信息解释移动原因

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
每个包都应包含自己的README：
packages/
├── cli/
│   └── README.md          # CLI包概述
├── registry/
│   └── README.md          # 注册服务器文档
├── registry-client/
│   └── README.md          # 客户端库文档
├── types/
│   └── README.md          # 类型定义文档
└── webapp/
    └── README.md          # Web应用文档

Maintenance

维护规范

Regular Reviews

定期审查

  • Quarterly review of docs/ for accuracy
  • Remove outdated documentation
  • Update examples to use latest version
  • Check for broken links
  • 每季度审查docs/目录下文档的准确性
  • 删除过时文档
  • 更新示例以使用最新版本
  • 检查失效链接

When Adding Features

添加功能时

  • Update relevant user docs in 
    docs/
  • Update internal docs in 
    development/docs/
    if needed
  • Add examples
  • Update CHANGELOG.md
  • 更新docs/目录下的相关用户文档
  • 若需要，更新development/docs/目录下的内部文档
  • 添加示例
  • 更新CHANGELOG.md

When Deprecating Features

弃用功能时

  • Add deprecation notice to docs
  • Provide migration guide
  • Keep docs until feature is removed
  • Update CHANGELOG.md
  • 在文档中添加弃用通知
  • 提供迁移指南
  • 保留文档直至功能完全移除
  • 更新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
文档类型存放位置受众示例
内部开发文档
development/docs/
贡献者CI/CD、发布流程
用户面向文档
docs/
终端用户指南、教程
项目根目录文档
/
所有人员README、LICENSE
AI技能文档
.claude/skills/
AI助手故障排查
包文档
packages/*/README.md
包使用者API参考

Tools

工具

Documentation Generators

文档生成器

  • TypeDoc - For TypeScript API docs (future)
  • VitePress or Docusaurus - For docs/ site (future)
  • TypeDoc - 用于生成TypeScript API文档（规划中）
  • VitePress 或 Docusaurus - 用于搭建docs/站点（规划中）

Linting

代码检查

bash
undefined
bash
undefined

Check markdown

检查Markdown格式

markdownlint docs/
markdownlint docs/

Check links

检查链接有效性

markdown-link-check docs/**/*.md
undefined
markdown-link-check docs/**/*.md
undefined

Building Docs Site (Future)

构建文档站点（规划中）

bash
cd docs/
npm run build
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
prpm/
├── README.md                    # 项目概述
├── CONTRIBUTING.md              # 贡献指南
├── CHANGELOG.md                 # 版本历史
├── ROADMAP.md                   # 未来规划
├── development/
│   └── docs/
│       ├── GITHUB_WORKFLOWS.md  # CI/CD参考
│       ├── PUBLISHING.md        # 发布流程
│       ├── DEVELOPMENT.md       # 开发环境搭建
│       └── DOCKER.md            # 服务配置
├── docs/
│   ├── getting-started.md       # 用户入门
│   ├── cli-reference.md         # 命令参考
│   ├── package-authoring.md     # 包创建指南
│   └── api/
│       └── registry-client.md   # API文档
└── .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
prpm/
├── README.md
├── WORKFLOWS.md                 # 应存放于development/docs/
├── USER_GUIDE.md                # 应存放于docs/
├── dev-setup.md                 # 应存放于development/docs/
└── troubleshooting.md           # 受众/存放位置不明确

Version

版本信息

Last Updated: 2025-10-21 Applies To: PRPM v2+ Review Date: 2026-01-21
最后更新： 2025-10-21 适用版本： PRPM v2+ 下次审查日期： 2026-01-21