技术文档最佳实践指南，涵盖结构层次、README撰写、API文档、维护策略及常见反模式，助力打造清晰可维护的技术文档。
说明：
## 核心用法
本技能提供一套系统化的技术文档编写框架，涵盖从README到完整文档站的全生命周期管理。
**文档结构五层模型**：
– **README**（5分钟快速上手）：一句话描述、安装命令、可运行示例、文档链接
– **Getting Started**（完整教程）：引导初学者完成一个完整工作流
– **Guides**（任务导向）：聚焦”如何做”而非功能罗列
– **Reference**（详尽参考）：API/CLI完整文档，适合查询不适合学习
– **Troubleshooting**（问题排查）：收录常见错误及解决方案，优化搜索体验
**关键执行要点**：
– 代码示例必须完整可运行（含导入、配置、预期输出），禁止片段代码
– API文档需包含：方法、路径、参数、请求体、响应、错误码、认证方式、速率限制
– 文档与代码同仓库管理，通过CI检测死链，将示例作为测试用例
**写作规范**：
– 祈使语气（”Run the command”）、第二人称（”you”）、现在时态
– 短句优先、主动语态、避免内部术语
– 错误消息原文收录，多别名覆盖搜索词
**版本管理**：
– 主版本分离文档（`/docs/v2/`），提供迁移指南
– 标注审查日期（”Last verified: 2024-01″），激进删除过时内容
## 显著优点
– **实战导向**：所有建议均针对真实失败场景（未经测试的示例、死链、版本漂移）
– **可执行性强**：提供具体检查清单（如README四要素、API文档六要素）
– **维护友好**：强调”Docs live next to code”，将文档质量纳入CI/CD流程
– **用户中心**：聚焦”用户搜索什么”而非”我们想说什么”
## 潜在局限
– 主要针对软件/开发者工具场景，对非技术文档（如产品手册、法律文档）适用性有限
– 未涉及多语言文档、国际化排版、PDF/离线文档生成
– 缺乏文档工具链推荐（如Docusaurus、MkDocs、Slate等选型对比）
## 适合人群
– 开源项目维护者（优化README和贡献指南）
– 开发者体验（DX）团队构建文档站点
– 技术写作人员建立规范体系
– 初创团队快速搭建技术文档基础设施
## 常规风险
– **过度简化风险**：”5分钟上手”承诺若无法兑现，反而加剧用户流失
– **维护负担**：同仓库管理虽减少漂移，但增加PR复杂度和代码审查负荷
– **删除焦虑**：”激进删除”策略在合规要求严格的场景（金融、医疗）可能受限
会员专属
