（11752期）Documentation – 技术文档写作与维护最佳实践

技术文档写作与维护最佳实践 技术文档最佳实践指南，涵盖结构层次、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复杂度和代码审查负荷 删除焦虑："激进删除"策略在合规要求严格的场景（金融、医疗）可能受限 原始说明 Technical documentation patterns, structure, maintenance, and avoiding common documentation failures.