跳到主要内容

如何建设技术文档体系

问题​

你如何看待技术文档？你所在团队是如何建设和维护技术文档体系的？

回答思路​

为什么技术文档重要​

在前端团队中，文档的价值常被低估。但随着团队规模和项目复杂度增长，缺乏文档会导致：

  • 新人上手时间长（3 周 → 可以压缩到 1 周）
  • 同类问题反复被人问
  • 历史技术决策不可追溯，同样的坑反复踩
  • 关键知识集中在少数人身上（"bus factor"）

核心文档类型​

1. 项目 README（必须有）​

每个项目/仓库的入口文档，新人看完就能启动项目：

README.md 模板
# 项目名称

> 一句话描述项目的定位和目标

## 技术栈
- React 18 + TypeScript
- Vite 5
- Zustand + React Query

## 快速开始

### 环境要求
- Node.js >= 18
- pnpm >= 8

### 安装与启动
pnpm install
pnpm dev

### 环境变量
cp .env.example .env.local
# 填写必要的环境变量

## 项目结构
src/
├── components/    # 通用组件
├── features/      # 业务功能模块
├── hooks/         # 自定义 Hooks
├── services/      # API 请求
├── stores/        # 状态管理
├── utils/         # 工具函数
└── types/         # 类型定义

## 开发规范
- [编码规范](./docs/coding-standards.md)
- [Git 提交规范](./docs/git-convention.md)
- [Code Review 指南](./docs/code-review.md)

## 部署
- 测试环境：推送到 develop 分支自动部署
- 生产环境：推送到 main 分支 + Tag 触发部署

## 相关链接
- [设计稿](Figma 链接)
- [接口文档](API 文档链接)
- [监控面板](Grafana/Sentry 链接)

2. ADR — 架构决策记录​

ADR（Architecture Decision Record）记录"为什么选择了 A 而不是 B"，是最容易被忽视但最有价值的文档：

docs/adr/001-state-management.md
# ADR 001: 选择 Zustand 作为状态管理方案

## 状态
已采纳（2024-06-15）

## 背景
项目从无到有搭建，需要选择合适的状态管理方案。
团队 5 人，React 经验 2-5 年不等。

## 考虑的方案
1. **Redux Toolkit** — 生态最成熟但样板代码多
2. **Zustand** — 轻量、TS 友好、学习成本低
3. **Jotai** — 原子化管理，适合细粒度状态
4. **React Context** — 原生方案但性能有坑

## 决策
选择 **Zustand**

## 理由
- 团队中中级开发者居多，Zustand 学习曲线最低
- 项目状态复杂度中等，不需要 Redux 的重武器
- TypeScript 类型推导体验最好
- Bundle Size 仅 1.1KB，对性能无负担

## 影响
- 团队需要学习 Zustand 的使用模式（约 2 小时）
- 放弃了 Redux DevTools 的部分高级功能
- 后续如果状态复杂度激增，可能需要评估迁移成本
ADR 的核心价值

半年后新同事问"为什么用 Zustand 不用 Redux？"，不需要找人问，直接看 ADR 就清楚了。ADR 保护的是决策的上下文，防止未来的人在不了解背景的情况下做出错误的推翻。

3. 开发规范文档​

docs/coding-standards.ts
// 将团队的编码约定文档化，而不是只靠口口相传

// ✅ 好的规范文档示例
const codingStandards = {
  // 命名规范
  naming: {
    component: 'PascalCase',    // UserProfile.tsx
    hook: 'camelCase, use前缀',  // useUserProfile.ts
    util: 'camelCase',          // formatDate.ts
    constant: 'UPPER_SNAKE',    // MAX_RETRY_COUNT
    type: 'PascalCase',         // UserProfileProps
    cssModule: 'camelCase',     // styles.userName
  },
  
  // 文件组织
  fileOrganization: {
    单个组件最大行数: 300,
    单个函数最大行数: 50,
    导出方式: '优先 named export',
    组件结构: '类型定义 → hooks → 事件处理 → 渲染逻辑 → JSX',
  },
  
  // 注释规范
  comments: {
    when: '当代码不能自解释时',
    format: 'JSDoc for 公共 API, 行注释 for 业务逻辑',
    language: '中文',
    todo: '必须带日期和负责人: // TODO(zhangsan 2024-01-15): 描述',
  },
};

4. 知识库 / FAQ​

docs/faq.ts
// 将团队反复被问到的问题沉淀为文档

interface FAQEntry {
  question: string;
  answer: string;
  tags: string[];
  addedBy: string;
  date: string;
}

const teamFAQ: FAQEntry[] = [
  {
    question: '本地启动后 API 请求 401 怎么办？',
    answer: '检查 .env.local 中的 TOKEN 是否过期，重新获取：...',
    tags: ['环境', '常见问题'],
    addedBy: '张三',
    date: '2024-06-01',
  },
  {
    question: '为什么构建后图片路径 404？',
    answer: '图片需要放在 public/ 而不是 src/assets/，或使用 import 导入...',
    tags: ['构建', '静态资源'],
    addedBy: '李四',
    date: '2024-06-15',
  },
];

文档工具链选择​

工具适用场景优势
项目内 MarkdownREADME/ADR/规范与代码同源，版本可追溯
Docusaurus/VitePress对外文档站/组件库文档美观、搜索、版本管理
Notion/飞书文档知识库/FAQ/会议纪要协作方便、搜索强
Storybook组件文档可交互、实时预览
Swagger/OpenAPIAPI 文档接口规范、可测试
注意

不要在多个地方维护同一份文档。选定一个 Single Source of Truth，其他地方只放链接。

让文档活下去的关键机制​

文档最大的问题不是写不出来，而是写了没人维护。关键是建立机制：

三个核心机制：

  1. 流程卡点：PR 检查是否有文档更新，技术方案评审必须有 ADR
  2. 模板化：提供标准模板，降低写文档的心理门槛
  3. 定期清理：每季度文档大扫除，标记过时文档、删除无用文档

常见面试问题​

Q1: 你们团队的文档体系是怎样的？​

答案：

按照层次来组织：

  1. 项目级：每个仓库有 README + CONTRIBUTING.md
  2. 架构级：ADR 记录所有重要技术决策
  3. 规范级：统一的编码规范、Git 规范、Code Review 标准
  4. 知识级：飞书知识库存放 FAQ、踩坑记录、技术分享沉淀
  5. API 级：Swagger 自动生成 + 注释补充

Q2: 如何推动团队写文档？​

答案：

  1. 降低成本：提供现成模板，用 AI 辅助生成初稿
  2. 流程绑定：PR 模板中要求填写变更说明，技术方案必须先写文档
  3. 激励机制：将文档贡献纳入绩效，季度评选最佳文档
  4. 以身作则：团队负责人带头写，写得好别人才会跟

Q3: ADR 和技术方案有什么区别？​

答案：

维度ADR技术方案
长度1-2 页3-10 页
重点决策和理由实施细节
写作时机做出决策后开发前
生命周期永久存档项目结束后参考价值降低
目标读者未来的团队成员当前的开发团队

ADR 回答的是"为什么这样做"，技术方案回答的是"怎么做"。两者互补，不冲突。

Q4: 如何保证文档不过时？​

答案：

  1. Docs as Code：文档和代码在同一个仓库，改代码时同步改文档
  2. CI 检查：检测文档中的链接是否失效、代码示例是否可运行
  3. 过期标记：给文档加 lastUpdated 字段，超过 6 个月标记为待 Review
  4. 文档 Owner：每份关键文档指定负责人，变更时通知
  5. 季度大扫除：每季度安排 1 天做文档清理

Q5: 文档写在代码仓库里还是独立文档平台？​

答案：

根据文档类型决定：

  • 与代码强相关的 → 放代码仓库（README、ADR、组件文档、API 注释）
  • 与流程相关的 → 放文档平台（Onboarding、流程规范、会议记录）
  • 组件/API 文档 → 用 Storybook/Swagger 自动生成

原则：代码文档跟着代码走（同步更新），流程文档放在协作平台（方便搜索和编辑）。

相关链接​