Documentation

核心用法

本技能提供一套系统化的技术文档编写框架，涵盖从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复杂度和代码审查负荷
• 删除焦虑："激进删除"策略在合规要求严格的场景（金融、医疗）可能受限

核心功能与价值

该 Skill 是一套系统化的技术文档编写方法论，专注于解决开发者文档质量差、维护难的问题。它将文档体系划分为清晰的五层结构：README（5分钟快速上手）、Getting Started（完整入门教程）、Guides（任务导向指南）、Reference（详尽的API参考）和 Troubleshooting（错误排查）。这种分层设计既满足不同深度用户的需求，又避免了信息过载。

显著优点

实战导向的结构设计：强调"5分钟到首次成功"原则，要求README必须包含一句话描述、一键安装命令、可运行的最小示例和完整文档链接——缺失任一都会导致用户流失。这种以转化率为核心的文档思维在同类指南中较为少见。

可维护性机制：提出文档与代码同仓库、CI自动检测死链、可运行示例即测试等具体措施，直接针对"文档腐烂"这一行业通病。特别值得关注的是"删除过时文档"的激进主张，认为残缺文档比无文档危害更大。

精细的写作规范：从代码示例必须版本锁定（package@2.1.0而非package）、到使用祈使语气("Run"而非"You can run")、再到错误消息原文收录以优化搜索，这些细节体现了作者深厚的技术写作经验。

局限性与适用边界

框架特异性缺失：内容偏向通用原则，对特定技术栈（如Python的Sphinx、Rust的mdBook）的工具链集成缺乏具体指导，需要使用者自行补充。

团队协作流程浅层：虽提及"同PR维护"，但对文档评审机制、写作者与开发者权责划分、多语言文档管理等组织级问题覆盖不足。

国际化与可访问性未涉及：未讨论文档翻译、RTL语言支持、屏幕阅读器友好性等现代文档工程的重要维度。

适合人群

• 开源项目维护者：需快速建立专业文档形象的独立开发者或小团队
• 技术写作者：寻求系统化方法论提升内容质量的文档工程师
• 企业内部平台团队：需制定统一的API文档标准与写作规范
• 技术管理者：希望量化评估现有文档健康度的工程领导者

风险提示

本 Skill 本身为纯文档内容，无代码执行风险。但需注意：其建议的"可运行示例即测试"策略若实施不当，可能导致CI管道引入外部依赖风险；"版本锁定"建议虽稳妥，却可能让用户错过安全更新，需配合依赖更新提醒机制使用。