文档构建技能
概述
本技能帮助您生成各种技术文档，包括 API 文档、用户手册、开发指南等。
关键词: 文档编写、API 文档、用户手册、开发指南、技术文档、README
核心功能
1. API 文档生成
- •生成 RESTful API 文档
- •描述 API 端点、参数和响应
- •提供请求和响应示例
- •创建交互式 API 文档（如 Swagger/OpenAPI）
2. 用户手册编写
- •编写用户使用指南
- •创建快速入门教程
- •提供常见问题解答（FAQ）
- •设计操作步骤和截图
3. 开发指南创建
- •编写开发环境搭建指南
- •创建代码贡献指南
- •设计架构和设计文档
- •提供开发最佳实践
4. README 和项目文档
- •生成项目 README
- •创建安装和使用说明
- •编写变更日志（CHANGELOG）
- •设计项目结构说明
使用指南
文档编写原则
- •清晰性: 文档应清晰易懂，避免歧义
- •完整性: 覆盖所有重要功能和场景
- •准确性: 确保文档与代码一致
- •实用性: 提供实际可用的示例
- •可维护性: 文档应易于更新和维护
文档结构
- •概述: 项目或功能的概述
- •快速开始: 快速上手指南
- •详细说明: 详细的功能说明
- •API 参考: API 接口文档（如适用）
- •示例: 使用示例和代码示例
- •常见问题: FAQ 和故障排除
文档格式
- •Markdown（.md）
- •reStructuredText（.rst）
- •HTML
- •PDF（如需要）
输出格式
文档应包含：
- •文档文件: 完整的文档内容
- •目录结构: 清晰的章节和目录
- •代码示例: 实际可运行的代码示例
- •图表和截图: 可视化说明（如需要）
- •链接和引用: 相关资源的链接
最佳实践
- •使用清晰的标题和章节结构
- •提供实际可用的代码示例
- •保持文档与代码同步更新
- •使用图表和截图辅助说明
- •编写易于搜索的文档
- •考虑不同水平的读者
- •定期审查和更新文档