文档工程
文档是软件产品的重要组成部分，良好的文档降低用户学习成本、减少支持成本、提高团队协作效率。文档工程是系统化地创建、维护和改进文档的实践，将文档视为一等公民，与代码同等重视。
文档类型
用户文档
用户手册：介绍产品的使用方法，面向最终用户。
快速开始：帮助用户快速上手，通常是 5-10 分钟的入门教程。
API 文档：描述 API 的使用方法，包括请求响应示例。
故障排查：列出常见问题和解决方案。
开发文档
架构文档：描述系统架构、设计决策、技术选型。
开发指南：指导开发者如何搭建开发环境、构建项目、运行测试。
代码规范：编码风格、命名规范、最佳实践。
部署文档：描述如何部署应用，包括环境要求、配置说明。
运维文档
监控手册：监控指标含义、告警处理流程。
应急预案：常见故障的处理步骤，联系人信息。
变更记录：系统变更的历史记录，便于问题追溯。
API 文档
OpenAPI 规范
OpenAPI（原 Swagger）是 RESTful API 的文档标准。
信息描述：API 基本信息（标题、版本、描述）。
路径定义：每个端点的路径、方法、参数、响应。
数据模型：请求和响应的数据结构。
安全定义：认证方式（API Key、OAuth2）。
文档生成
Swagger UI：根据 OpenAPI 规范自动生成交互式文档。
Redoc：生成美观的静态文档页面。
代码注释：从代码注释自动生成文档（如 Java Javadoc、Go Doc）。
文档示例
清晰的示例是 API 文档的关键。
请求示例：展示真实的请求格式，包括 headers、body。
响应示例：展示成功和失败的响应。
错误码：列出所有可能的错误码和含义。
使用场景：展示 API 的典型使用场景。
文档工具
Markdown
Markdown 是轻量级标记语言，易于编写和阅读。
语法简单：基本语法可以在几分钟内学会。
广泛支持：几乎所有文档平台都支持 Markdown。
版本控制：纯文本格式，适合 Git 管理。
静态站点生成器
VitePress：基于 Vite 的文档生成器，本站使用。
Docusaurus：Facebook 开源的文档平台，支持多版本。
Hugo：Go 编写的快速静态站点生成器。
GitBook：商业文档平台，提供托管服务。
API 文档工具
Swagger：OpenAPI 规范的实现工具。
Postman：API 开发和文档平台。
Apifox：国产 API 管理工具，支持文档、Mock、测试。
架构文档工具
Mermaid：文本到图表的工具，支持流程图、时序图、状态图。
PlantUML：UML 图表工具，支持类图、时序图、组件图。
C4 Model：架构图描述语言，关注上下文、容器、组件、代码。
文档最佳实践
文档即代码
版本控制：文档与代码同仓库管理，版本同步。
审查流程：文档变更与代码变更一起审查。
自动化构建：文档作为构建流程的一部分，自动生成和部署。
文档结构
层次清晰：文档有明确的层次结构，便于导航。
搜索友好：提供搜索功能，快速定位内容。
多级导航：侧边栏提供多级导航，展示文档结构。
文档内容
面向读者：根据读者背景调整内容深度。
图文并茂：使用图表、截图辅助说明。
示例驱动：提供可运行的示例，帮助读者理解。
保持更新：代码变更时同步更新文档，避免文档过时。
文档风格
简洁明了：用简单的语言表达复杂的概念，避免术语堆砌。
主动语态：使用主动语态，如"点击按钮"而非"按钮被点击"。
一致性：术语翻译、格式风格保持一致。
交互式文档
可运行示例：在文档中嵌入可运行的代码片段。
交互式 API：文档中的 API 可以直接调用。
实时预览：修改代码实时预览效果。
文档维护
文档生命周期
创建：新功能开发时同步创建文档。
更新：代码变更时更新相关文档。
废弃：功能移除时标记文档为废弃。
归档：旧版本文档归档保留，便于参考。
文档审查
技术审查：确保文档内容准确、完整。
语言审查：确保文档语言通顺、易懂。
用户反馈：收集用户反馈，持续改进文档。
文档指标
页面浏览：了解哪些文档最常被访问。
停留时间：了解文档是否有帮助。
搜索关键词：了解用户在寻找什么。
跳出率：了解文档是否满足用户需求。
文档文化
文档优先
先写文档：开发功能前先写文档，明确需求。
文档驱动：文档是设计的一部分，而非开发后的补充。
文档评审：文档与代码同等重视，需要评审才能合并。
知识共享
文档分享：定期分享文档编写经验。
文档培训：培训团队成员如何编写高质量文档。
文档激励：认可和奖励文档贡献者。
持续改进
定期审查：定期审查文档，更新过时内容。
用户调研：了解用户文档需求，改进文档结构。
工具优化：持续优化文档工具，提高编写效率。
文档工程是软件工程的重要组成部分，良好的文档降低沟通成本、提高团队效率、改善用户体验。建立文档优先的文化，将文档视为一等公民，是构建高质量软件产品的关键。