关于 technical-writing
面向开发者和技术团队的文档写作技能，涵盖文档类型选择、背景收集、内容组织、示例编写和发布前检查。
主要功能
- 01API 与用户文档写作指导
- 02评估受众与文档范围
- 03内容结构组织建议
- 04可运行代码示例指导
- 05发布前质量检查清单
适用场景
- 01撰写 API 参考或用户指南
- 02编写含实践示例的教程
- 03准备架构文档或技术规范
- 04检查文档的清晰度与完整性
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/technical-writing确认已加载。
附带文件references/documentation-types-and-workflows.mdreferences/writing-guidelines.md
详细介绍
技术写作
创作专业的技术文档，结构清晰、详略得当，并以用户为中心。
工作流
1. 确定文档类型
确定所需的文档类型：
- API 文档 - REST、GraphQL、webhook、身份验证
- 用户指南 - 功能、操作指南、故障排除
- 教程 - 以学习为导向，包含实践示例
- 架构文档 - 系统设计、技术决策
- README 文件 - 项目概览、快速入门
- 发行说明 - 变更、迁移、重大变更
- 技术规范 - 要求、限制
详细模板和模式： 加载 documentation-types-and-workflows.md
2. 收集背景信息
写作前收集必要信息：
- 受众 - 开发者、最终用户、管理者、管理员
- 技术深度 - 初级、中级、高级
- 范围 - 需要编写文档的代码库/API/系统
- 标准 - 风格指南或组织要求
- 相关文档 - 可供参考或整合的现有文档
3. 组织内容
遵循清晰的组织原则：
- 以概览/简介开篇
- 使用描述性标题层级（H1 → H2 → H3）
- 文档包含超过 3 个章节时，添加目录
- 按逻辑对相关信息分组
- 在概念之后立即提供示例
- 为复杂工作流添加图表/可视化内容
4. 清晰写作
遵循核心写作原则：
- 主动语态 - 使用“API 会返回……”，而非“响应会被返回……”
- 具体明确 - 使用“响应时间 < 200ms”，而非“响应快速”
- 定义缩写 - 首次使用时写出“API（应用程序编程接口）”
- 术语一致 - 在整份文档中使用相同的术语
- 使用祈使句说明操作 - 使用“运行该命令”，而非“你应该运行……”
- 提供示例 - 为每个概念提供代码/输出
全面的风格指南： 加载 writing-guidelines.md
5. 添加代码示例
代码示例要求：
- 在代码块中指定语言：
python、javascript - 提供完整、可运行的示例（而非代码片段）
- 包含输入/输出对
- 为复杂逻辑添加说明性注释
- 发布前测试所有代码
6. 审核和验证
质量保证清单：
- ✓ 验证技术准确性
- ✓ 测试所有代码示例
- ✓ 检查清晰度和完整性
- ✓ 确保术语一致
- ✓ 验证所有链接和引用
文档模板
README 文件
项目文档的必要组成部分：
# Project Name
Brief description of what the project does
## Features
- Key feature 1
- Key feature 2
- Key feature 3
## Installation
[step-by-step installation commands]
## Quick Start
[minimal working example]
## Configuration
[environment variables or config options]
## License
[license type]
发行说明
版本发布的结构：
# Version X.X.X - YYYY-MM-DD
## Summary
[High-level overview of this release]
## New Features
- Feature description (#issue-number)
- Feature description (#issue-number)
## Bug Fixes
- Fix description (#issue-number)
- Fix description (#issue-number)
## Breaking Changes
⚠️ **Change that breaks compatibility**
Migration guide: [step-by-step migration instructions]
## Deprecations
- Deprecated feature (will be removed in vX.X)
质量标准
发布前的文档质量检查清单：
- 准确性 - 所有技术细节均正确
- 完整性 - 涵盖所有必要主题
- 清晰度 - 目标受众能够理解内容
- 示例 - 包含并测试可运行的代码
- 结构 - 组织合理，标题清晰
- 一致性 - 术语和格式一致
- 链接 - 所有超链接均有效
- 语法 - 无拼写或语法错误
- 时效性 - 版本号和日期均为最新
应避免的常见问题
- 想当然地假设读者具备相关知识 - 定义所有缩写和技术术语
- 指示含糊 - 使用具体示例明确说明
- 遗漏错误场景 - 记录错误及其解决方案
- 示例过时 - 定期测试并更新代码
- 术语不一致 - 全文使用统一术语
- 遗漏前置条件 - 提前列出所有要求
- 格式不佳 - 正确使用标题、列表和代码块
- 没有示例 - 始终包含可运行的代码示例
- 受众层级不匹配 - 根据读者调整技术深度
- 文本密集难读 - 拆分为便于浏览的章节，并设置清晰的标题
参考文件
- documentation-types-and-workflows.md - API 文档、用户指南、教程、架构文档和技术规范的完整模板与模式
- writing-guidelines.md - 关于清晰度、主动语态、具体性、一致性、标题层级、代码格式和列表的详细风格规则
评论
支持 Markdown