贡献者文档与用户文档如何分离

wen 开源项目 2026-07-18 2

本文目录导读：

贡献者文档与用户文档如何分离

核心定位差异（这是分离的基础）
物理分离策略（如何存放与组织）
内容入口与导航的分离
特定内容的放置策略
交付与文档即代码的实践
分离的最终标志

贡献者文档与用户文档的分离，核心目的是针对不同受众提供不同深度的内容，避免用户被技术细节淹没,同时让贡献者能快速找到开发和维护所需的信息。

分离不仅仅是“分文件夹存放”，而是从内容定位、组织结构、写作风格、交付形式四个维度进行系统性规划。

以下是具体的方法论和最佳实践：

核心定位差异（这是分离的基础）

首先要在团队内明确两个文档集的根本区别：

维度	用户文档	贡献者文档
目标读者	使用产品的最终用户、管理员	开发者、测试者、运维、社区贡献者
核心目标	教会用户“怎么用”产品解决问题	教会开发者“怎么改”代码或扩展功能
关注点	易用性、快速上手、故障排除	准确性、完整性、可复现性
写作风格	平实、简单、避免术语（或解释术语）	技术精确、可假设读者是开发者

物理分离策略（如何存放与组织）

最直接的方法是在仓库中建立独立目录，或者使用独立仓库/站点。

方案1：同仓库、不同目录（推荐中小型项目）

project-root/
├── README.md
├── docs/                    # 用户文档主目录
│   ├── guide/               # 入门指南
│   ├── tutorials/           # 教程
│   ├── reference/           # API参考、配置项
│   └── troubleshooting/     # 常见问题
├── dev-docs/                # 贡献者文档主目录（或命名为 internal/）
│   ├── CONTRIBUTING.md      # 贡献指南（入口文件）
│   ├── architecture.md      # 架构设计
│   ├── setup.md             # 本地开发环境搭建
│   ├── coding-standards.md  # 编码规范
│   ├── testing.md           # 测试指南
│   └── release-process.md   # 发布流程
└── src/                     # 源代码

优点：维护简单，与代码版本同步。缺点：文档站点构建时需配置路由区分（docs.example.com vs contributing.example.com）。

方案2：独立仓库与站点（推荐大型或商业化项目）

用户文档仓库 (如 project-user-docs)：构建到 docs.example.com
贡献者文档仓库 (如 project-dev-docs)：构建到 dev-docs.example.com 或 github.com/org/project/wiki

优点完全解耦，权限管理清晰，站点风格可差异化。缺点：跨仓库引用复杂，维护两个站点的CI/CD。

内容入口与导航的分离

读者需要能一眼找到自己该去哪。

在README中做明确分流： README.md 顶部应包含：
- 📖 用户文档
- 🛠️ 贡献指南
- 🐛 报告问题
在用户文档中隐式分离：用户文档中不提供指向贡献者文档的直接链接,除非是可选的高级定制。

正确做法：用户文档只说“如需要自定义插件，请参考...”,而不会把插件开发的API文档放进来。
在贡献者文档中显式声明：贡献者文档开头应声明：“本文档面向希望修改XXXX代码的开发者，如果你只是想使用XXXX，请移步[用户文档]。”

特定内容的放置策略

交付与文档即代码的实践

标签与元数据：在文档的YAML Front Matter中使用标签区分受众：
```
--- "安装指南"
audience: user
# 或 audience: contributor
---
```
这样构建系统可以自动过滤和分页。
构建工具配置：使用 MkDocs、Docusaurus 或 Read the Docs 时，可以在 mkdocs.yml 或 docusaurus.config.js 中为 dev-docs 配置独立的路由：
```
# mkdocs.yml 示例（多文档站点）
nav:
  - 用户指南: 'user/'
  - 开发者指南: 'dev/'
```
代码注释与文档的分离：
- API文档（如Swagger/OpenAPI）通常由代码注释生成，这是用户参考文档的一部分。
- 架构文档（ADR）、设计文档应放在贡献者文档中,它们通常手动编写。

分离的最终标志

检查项	用户文档	贡献者文档
读者能独立理解内容吗？	是，无需阅读代码	是，读者有代码知识
包含代码片段吗？	只包含调用示例、配置片段	包含完整的构建、测试、PR代码
讨论项目内部架构吗？	从不提及	深度讨论
提供故障排除吗？	针对用户操作问题	针对开发环境、依赖问题

核心原则：用户文档教“做什么 (What)”，贡献者文档教“为什么 (Why) 和怎么做 (How) 只要坚持这一原则,分离就会自然发生。