文档生成

⭐⭐ 初中级 | 快速生成完整的技术文档

好的技术文档应该：

1. 清晰 - 易于理解，不含歧义
2. 完整 - 涵盖所需的内容
3. 准确 - 与代码保持同步
4. 可维护 - 易于更新
5. 适用 - 针对不同的受众

文档的类型：

• API文档 - 接口定义和用法
• 架构文档 - 系统设计和组件
• 部署文档 - 安装和配置
• 故障排查 - 常见问题和解决
• 开发指南 - 如何贡献代码
• 用户手册 - 产品使用说明

🎯 原则1: 代码即文档

• 使用清晰的代码
• 有意义的变量和函数名
• 包含docstring/注释

🎯 原则2: 文档靠近代码

• 代码注释
• docstring
• README.md在项目根目录
• 避免单独维护的wiki（容易过时）

🎯 原则3: 文档驱动

• 先写文档，明确接口
• 然后实现代码
• 文档和代码同步更新

🎯 原则4: 针对受众

• API文档给调用者
• 架构文档给架构师
• 部署文档给运维
• 不要一份文档应付所有人

场景1: API文档生成

Prompt:

请为这个API生成文档。

API实现：
[代码或源文件]

需要生成：
1. API概述
2. 认证方式
3. 所有端点的说明（方法、参数、返回值）
4. 请求/响应示例
5. 错误码说明
6. 速率限制说明

格式：
- Markdown格式
- 或生成OpenAPI/Swagger规范

输出应该包含完整的API参考。

场景2: 架构文档

Prompt:

请根据这些信息生成架构文档。

系统概述：
[系统的功能和目标]

主要组件：
1. [组件1]: [说明]
2. [组件2]: [说明]
3. ...

关键决策：
[列出关键的架构决策]

数据流：
[描述数据流向]

技术栈：
[使用的技术]

需要生成：
1. 架构概览（文字说明）
2. 架构图（ASCII或Mermaid）
3. 组件说明
4. 技术选择理由
5. 扩展性考虑

场景3: 部署文档

Prompt:

请生成应用的部署文档。

应用信息：
- 应用名：[名称]
- 技术栈：[栈]
- 依赖：[依赖列表]
- 配置：[配置说明]

部署步骤：
1. [环境准备]
2. [依赖安装]
3. [配置设置]
4. [启动应用]
5. [验证]

需要包含：
1. 系统要求
2. 详细的部署步骤
3. 故障排查
4. 常见问题
5. 回滚步骤

场景4: 故障排查指南

Prompt:

请为应用生成故障排查指南。

常见问题：
1. [问题1]: [症状] → [解决方案]
2. [问题2]: [症状] → [解决方案]
3. ...

日志位置：[日志在哪里]

监控指标：[应该监控什么]

需要生成：
1. 故障排查流程图
2. 常见问题和解决方案
3. 日志分析指南
4. 联系方式和升级流程

好的策略:

• 代码改动时同时更新文档
• 使用版本控制管理文档
• 定期审视和更新
• 用CI自动生成API文档
• 收集用户反馈改进文档

不好的策略:

• 单独维护一份wiki（容易过时）
• 文档滞后（代码改了文档没改）
• 没有版本管理
• 缺乏维护，成为垃圾信息来源

文档是知识转移的关键，好的文档能：

• 帮助新人快速上手
• 减少重复的问题提问
• 提高代码维护性
• 保留关键设计决策的理由

立即开始为你的项目补充和改进文档！