5.7.1 文档该放哪里——文档目录结构
一句话破题
文档目录应该与代码结构对应，让人一看就知道去哪找。
推荐的目录结构
my-project/
├── docs/ # 文档目录
│ ├── README.md # 文档首页
│ ├── getting-started.md # 快速开始
│ ├── api/ # API 文档
│ │ ├── auth.md # 认证相关
│ │ └── posts.md # 文章相关
│ ├── guides/ # 使用指南
│ │ ├── deployment.md # 部署指南
│ │ └── development.md # 开发指南
│ └── architecture/ # 架构说明
│ └── overview.md # 架构概览
├── src/ # 源代码
│ ├── app/
│ │ └── api/
│ │ ├── auth/ ← 对应 docs/api/auth.md
│ │ └── posts/ ← 对应 docs/api/posts.md
│ └── ...
└── README.md # 项目入口文档与代码的对应关系
| 代码路径 | 文档路径 | 内容 |
|---|---|---|
src/app/api/auth/ | docs/api/auth.md | 认证接口说明 |
src/app/api/posts/ | docs/api/posts.md | 文章接口说明 |
prisma/schema.prisma | docs/architecture/database.md | 数据库设计 |
src/lib/ | docs/architecture/libs.md | 工具函数说明 |
最小化文档结构
对于个人项目，可以更简化：
my-project/
├── docs/
│ ├── README.md # 项目说明 + 快速开始
│ ├── api.md # API 文档（所有接口）
│ └── deployment.md # 部署说明
├── src/
└── README.md # 项目入口（指向 docs/）文档命名规范
✅ 好的命名
- getting-started.md # 小写 + 连字符
- api-authentication.md
- deploy-to-vercel.md
❌ 不好的命名
- GettingStarted.md # 避免驼峰
- api authentication.md # 避免空格
- 部署说明.md # 避免中文文件名文档入口设计
项目 README.md 应该提供清晰的导航：
markdown
# My Blog
一个使用 Next.js 构建的个人博客系统。
## 快速开始
\`\`\`bash
pnpm install
pnpm dev
\`\`\`
## 文档
- [开发指南](./docs/development.md)
- [API 文档](./docs/api.md)
- [部署说明](./docs/deployment.md)
## 技术栈
- Next.js 16
- Prisma
- PostgreSQL让 AI 帮你设计目录
你：帮我设计博客项目的文档目录结构
AI：## 推荐文档结构
\`\`\`
docs/
├── README.md # 文档首页和导航
├── getting-started.md # 快速开始
├── development.md # 开发环境搭建
├── api/
│ ├── README.md # API 概览
│ ├── authentication.md # 认证接口
│ ├── posts.md # 文章接口
│ └── categories.md # 分类接口
├── deployment/
│ ├── vercel.md # Vercel 部署
│ └── docker.md # Docker 部署
└── architecture/
├── overview.md # 架构概览
└── database.md # 数据库设计
\`\`\`
根据你的项目规模，可以简化为：
\`\`\`
docs/
├── README.md # 所有内容都在这里
└── api.md # API 文档单独一个
\`\`\`实用建议
- 就近原则：相关的文档放在一起
- 扁平优先：不要嵌套太深
- 命名直观：看文件名就知道内容
- 及时归档：过时文档移到 archive 目录