文档组织最佳实践

2026年2月6日

文档组织最佳实践

良好的文档组织结构可以提升知识库的可维护性和可读性。

📁 推荐的目录结构

个人知识库

my-wiki/
├── README.md                  # 首页，知识库介绍
├── ABOUT.md                   # 关于我
├── images/                    # 全局图片
│
├── 技术笔记/
│   ├── README.md              # 分类索引
│   ├── images/
│   ├── JavaScript.md
│   ├── Python.md
│   └── Docker.md
│
├── 项目经验/
│   ├── README.md
│   ├── images/
│   ├── 项目A.md
│   └── 项目B.md
│
└── 学习资源/
    ├── README.md
    ├── 书籍推荐.md
    └── 课程笔记.md

团队文档

team-wiki/
├── README.md                  # 团队介绍
├── ABOUT.md                   # 团队文化
│
├── 开发规范/
│   ├── README.md
│   ├── 代码规范.md
│   ├── Git规范.md
│   └── 文档规范.md
│
├── 技术架构/
│   ├── README.md
│   ├── images/
│   ├── 系统架构.md
│   ├── 数据库设计.md
│   └── API文档.md
│
├── 项目文档/
│   ├── README.md
│   ├── 项目A/
│   │   ├── README.md
│   │   ├── 需求文档.md
│   │   └── 技术方案.md
│   └── 项目B/
│       └── README.md
│
└── 运维手册/
    ├── README.md
    ├── 部署指南.md
    └── 故障处理.md

产品文档

product-wiki/
├── README.md                  # 产品介绍
├── ABOUT.md                   # 关于产品
│
├── 快速开始/
│   ├── README.md
│   ├── 安装指南.md
│   ├── 快速入门.md
│   └── 常见问题.md
│
├── 功能文档/
│   ├── README.md
│   ├── 功能A.md
│   ├── 功能B.md
│   └── 功能C.md
│
├── API文档/
│   ├── README.md
│   ├── 认证.md
│   ├── 用户API.md
│   └── 数据API.md
│
└── 更新日志/
    ├── README.md
    ├── v1.0.0.md
    └── v1.1.0.md

📝 文件命名规范

1. 使用有意义的名称

# 好的命名
系统架构设计.md
用户认证流程.md
Docker部署指南.md

# 不好的命名
文档1.md
新建文档.md
未命名.md

2. 统一命名风格

中文文档:

技术架构.md
部署指南.md
常见问题.md

英文文档:

architecture.md
deployment-guide.md
faq.md

3. 避免特殊字符

# 推荐
Docker部署指南.md
API接口文档.md

# 不推荐
Docker/部署/指南.md
API:接口:文档.md

🗂️ 分类管理

1. 按主题分类

wiki/
├── 前端开发/
├── 后端开发/
├── 数据库/
├── 运维部署/
└── 项目管理/

2. 按时间分类

blog/
├── 2024/
│   ├── 01-January/
│   ├── 02-February/
│   └── ...
└── 2025/
    └── ...

3. 按项目分类

projects/
├── 项目A/
│   ├── 需求/
│   ├── 设计/
│   └── 开发/
└── 项目B/
    └── ...

📋 README 文件

每个目录都应该有 README.md 文件：

---
title: 技术架构
description: 本目录包含系统架构相关文档
---

# 技术架构

## 文档列表

- [系统架构](./系统架构.md)
- [数据库设计](./数据库设计.md)
- [API设计](./API设计.md)

## 架构图

![系统架构](/api/image/04-最佳实践/文档组织/images/architecture.png)

## 相关资源

- [部署指南](../运维/部署指南.md)
- [开发规范](../规范/开发规范.md)

🔗 链接管理

1. 使用相对链接

# 推荐
[部署指南](./部署指南.md)
[上级目录](../README.md)

# 不推荐
[部署指南](/wiki/部署指南.md)

2. 链接到特定章节

[快速开始](./README.md#快速开始)
[配置说明](./配置.md#基础配置)

3. 外部链接

[PowerWiki GitHub](https://github.com/steven-ld/PowerWiki)
[Docker Hub](https://hub.docker.com/r/sayunchuan/powerwiki)

🏷️ 标签和元数据

使用 Frontmatter 添加元数据：

---
title: 文章标题
description: 文章描述
author: 作者名称
date: 2026-02-07
updated: 2026-02-07
keywords: 关键词1, 关键词2
tags: [标签1, 标签2, 标签3]
category: 分类名称
---

📊 文档模板

技术文档模板

---
title: 技术文档标题
description: 简短描述
author: 作者
date: 2026-02-07
tags: [技术, 教程]
---

# 技术文档标题

## 概述

简要介绍文档内容。

## 前置要求

- 要求1
- 要求2

## 步骤

### 1. 第一步

详细说明。

### 2. 第二步

详细说明。

## 示例

\`\`\`bash
# 示例代码
\`\`\`

## 常见问题

### Q: 问题1
A: 答案1

## 参考资料

- [链接1](url1)
- [链接2](url2)

项目文档模板

---
title: 项目名称
description: 项目简介
author: 项目负责人
date: 2026-02-07
tags: [项目, 文档]
---

# 项目名称

## 项目概述

项目背景和目标。

## 技术栈

- 前端: React
- 后端: Node.js
- 数据库: MongoDB

## 架构设计

![架构图](/api/image/04-最佳实践/文档组织/images/architecture.png)

## 功能列表

- [ ] 功能1
- [ ] 功能2
- [x] 功能3（已完成）

## 开发进度

\`\`\`mermaid
gantt
    title 项目进度
    section 开发
    需求分析 :done, 2026-01-01, 7d
    系统设计 :active, 2026-01-08, 10d
\`\`\`

## 团队成员

| 姓名 | 角色 | 职责 |
|------|------|------|
| 张三 | 项目经理 | 项目管理 |
| 李四 | 开发 | 后端开发 |

💡 维护建议

1. 定期更新

及时更新过时的内容
添加 updated 字段记录更新时间
在文档中标注版本信息

2. 保持一致性

统一的格式和风格
统一的命名规范
统一的目录结构

3. 添加导航

在 README 中添加目录
使用面包屑导航
提供相关文档链接

4. 版本控制

使用有意义的 commit 信息
定期备份重要文档
保留文档历史版本

🔍 搜索优化

1. 使用清晰的标题

# 好的标题
## Docker 部署指南
## 常见问题解答

# 不好的标题
## 指南
## 问题

2. 添加关键词

在 Frontmatter 中添加关键词：

keywords: Docker, 部署, 容器化, PowerWiki

3. 使用描述性文本

避免使用"点击这里"、"查看详情"等模糊的链接文本。

提示: 良好的文档组织是知识库成功的关键。花时间规划结构，会让后续维护更加轻松。

更新时间：2026年2月24日