核心用法
Documentation Writer 是一个技术文档写作技能，提供从 README 文件到 API 文档、用户指南和代码注释的完整写作框架。用户通过触发关键词（"documentation"、"readme"、"api docs"、"user guide"）即可激活该技能，获得结构化的文档模板和写作指导。
主要功能模块：
1. README 生成器：提供标准 README 结构（项目名、特性、快速开始、用法、配置、API、贡献指南、许可证），强调 3 步内完成安装、可运行示例、常见用例覆盖。
2. API 文档模板：包含端点文档结构（HTTP 方法、路径、描述、参数表、响应格式、错误码、请求示例、速率限制），支持自动生成式文档风格。
3. 用户指南框架：采用"先决条件 → 分步操作 → 故障排除 → 进阶步骤"的流程，强调单一概念单节、编号步骤、截图建议和问题预判。
4. 代码注释规范：明确注释应解释"为什么"而非"是什么"，涵盖复杂逻辑、非常规决策、变通方案（workarounds）和带上下文的 TODO，反例包括显而易见的代码注释。
文档原则体系：
- 受众优先：区分初学者/专家/内部/外部读者，匹配相应语调
- 展示优于描述：用具体数据（如"1M 记录 <2 秒"）替代模糊表述
- 完整示例：提供从导入到错误处理的端到端代码片段
- 版本管理：标注更新时间、版本号、弃用警告和变更日志
模式与工具：
- 快速开始（5 分钟上手指南）、FAQ、故障排除等可复用模式
- Markdown 最佳实践（标题层级、代码块、表格、列表）
- JSDoc、Python docstrings 等文档生成器语法
配套检查清单：
为 README、API 文档、用户指南、代码注释分别提供完成度检查项，确保文档质量。
显著优点
- 结构化程度高：提供即插即用的模板，降低文档写作的认知负担
- 受众意识强：明确的读者分层策略，避免"一刀切"的文档风格
- 实战导向：包含大量可直接运行的代码示例和真实场景的故障排除
- 维护友好：版本标注、弃用警告、变更日志等机制支持文档长期维护
- 反模式警示：列举"假设倾倒"（assumption dumping）、遗漏先决条件、过时示例、缺乏错误处理等常见错误并给出改进方案
潜在缺点与局限性
- 语言局限：主要面向英文技术文档写作，中文本地化场景需额外适配
- 框架特定性：JSDoc、Python docstrings 等示例偏向特定语言，对其他语言（如 Go、Rust）覆盖有限
- 无自动化集成：仅为写作指南，未提供与 CI/CD、文档站点生成的自动化集成方案
- 设计文档缺失：未涵盖系统架构图、ER 图、流程图等可视化文档的写作指导
- 无障碍与国际化：未涉及文档的可读性标准（如 WCAG）、多语言翻译工作流
适合人群
- 开源项目维护者需要撰写标准 README 和贡献指南
- 后端开发者需要为 REST/GraphQL API 编写参考文档
- 技术写作者（Technical Writer）寻找结构化写作框架
- 团队需要统一代码注释规范和文档风格
- 独立开发者快速生成项目文档模板
常规风险
- 模板僵化风险：过度依赖模板可能导致文档同质化，缺乏项目特色
- 示例过时风险：若技能本身未定期更新，提供的"最佳实践"可能落后于社区标准（如 README 中的 shields.io 徽章、新的 Markdown 扩展语法）
- 安全信息泄露：模板中的 API 密钥占位符（如
your-api-key）若被用户误用为真实密钥并提交到版本控制，可能导致凭证泄露 - 误导性保证：性能相关的注释（如"1M 记录 <2 秒"）若未实际基准测试，可能成为技术债务