11.3.1 文档结构：项目文档的组织方式
一句话破题
好的文档结构让人一眼就知道去哪里找想要的信息，降低认知负担。
核心价值
合理的文档结构能让你：
- 快速定位所需信息
- 新人更容易上手
- 文档更新更有条理
推荐的目录结构
docs/
├── README.md # 文档导航入口
├── getting-started/ # 快速开始
│ ├── installation.md
│ ├── configuration.md
│ └── first-project.md
├── guides/ # 使用指南
│ ├── authentication.md
│ ├── database.md
│ └── deployment.md
├── api/ # API 参考
│ ├── overview.md
│ ├── users.md
│ └── products.md
├── architecture/ # 架构设计
│ ├── overview.md
│ ├── data-flow.md
│ └── decisions/ # 架构决策记录
├── contributing/ # 贡献指南
│ ├── code-style.md
│ └── pull-requests.md
└── changelog/ # 变更记录
└── CHANGELOG.md文档类型说明
| 类型 | 目的 | 受众 |
|---|---|---|
| 快速开始 | 让新人5分钟跑起来 | 新用户 |
| 使用指南 | 解释如何完成特定任务 | 开发者 |
| API 参考 | 详细的接口说明 | 开发者 |
| 架构设计 | 解释系统如何工作 | 架构师、维护者 |
| 贡献指南 | 如何参与项目 | 贡献者 |
文档导航示例
markdown
<!-- docs/README.md -->
# 项目文档
## 快速开始
- [安装指南](./getting-started/installation.md)
- [配置说明](./getting-started/configuration.md)
- [第一个项目](./getting-started/first-project.md)
## 开发指南
- [认证系统](./guides/authentication.md)
- [数据库操作](./guides/database.md)
- [部署流程](./guides/deployment.md)
## API 文档
- [API 概览](./api/overview.md)
- [用户接口](./api/users.md)
- [产品接口](./api/products.md)
## 了解更多
- [架构设计](./architecture/overview.md)
- [贡献指南](./contributing/code-style.md)
- [更新日志](./changelog/CHANGELOG.md)架构决策记录
使用 ADR 记录重要的技术决策：
markdown
<!-- docs/architecture/decisions/001-use-prisma.md -->
# ADR 001: 使用 Prisma 作为 ORM
## 状态
已采纳
## 背景
项目需要一个类型安全的数据库访问层
## 决策
采用 Prisma 作为 ORM
## 理由
- 类型安全，与 TypeScript 集成好
- 自动生成迁移脚本
- 社区活跃，文档完善
## 后果
- 需要学习 Prisma 特定语法
- 复杂查询可能需要原生 SQL避坑指南
新手最容易犯的错
- 所有文档堆在一个文件里
- 没有导航入口，找不到文档在哪
- 文档命名不规范（如
doc1.md、新建文档.md） - 文档之间没有相互链接