（2762期）Documentation Writer – 技术文档写作完全指南

技术文档写作完全指南 专业文档生成器，覆盖 README、API 文档、用户指南和代码注释，提供结构化模板与最佳实践，帮助开发者撰写清晰、完整、可维护的技术文档。 使用说明 核心用法 Documentation Writer 是一个技术文档写作技能，提供从 README 文件到 API 文档、用户指南和代码注释的完整写作框架。用户通过触发关键词（"documentation"、"readme"、"api docs"、"user guide"）即可激活该技能，获得结构化的文档模板和写作指导。 主要功能模块： README 生成器：提供标准 README 结构（项目名、特性、快速开始、用法、配置、API、贡献指南、许可证），强调 3 步内完成安装、可运行示例、常见用例覆盖。 API 文档模板：包含端点文档结构（HTTP 方法、路径、描述、参数表、响应格式、错误码、请求示例、速率限制），支持自动生成式文档风格。 用户指南框架：采用"先决条件 → 分步操作 → 故障排除 → 进阶步骤"的流程，强调单一概念单节、编号步骤、截图建议和问题预判。 代码注释规范：明确注释应解释"为什么"而非"是什么"，涵盖复杂逻辑、非常规决策、变通方案（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 秒"）若未实际基准测试，可能成为技术债务 原始说明 Write clear, comprehensive documentation. Covers README files, API docs, user guides, and code comments. Create documentation that users actually read and un...