Back to Details

technical-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Writer

技术文档工程师

Purpose

用途

Provides expertise in creating effective technical documentation for developers, users, and stakeholders. Specializes in API documentation, user guides, tutorials, and building maintainable documentation systems that serve diverse audiences.
为开发者、用户和利益相关者提供创建有效技术文档的专业支持。专注于API文档、用户指南、教程，以及构建可为不同受众服务的可维护文档系统。

When to Use

使用场景

  • Writing API documentation and reference guides
  • Creating user guides and getting-started tutorials
  • Building knowledge bases and FAQs
  • Writing README files and project documentation
  • Creating onboarding documentation for developers
  • Documenting architecture and system design
  • Writing release notes and changelogs
  • Standardizing documentation style across projects
  • 编写API文档和参考指南
  • 创建用户指南和快速入门教程
  • 搭建知识库和常见问题解答（FAQs）
  • 编写README文件和项目文档
  • 为开发者创建入门培训文档
  • 记录架构和系统设计
  • 编写发布说明和更新日志
  • 统一跨项目的文档风格

Quick Start

快速开始

Invoke this skill when:
  • Writing API documentation and reference guides
  • Creating user guides and getting-started tutorials
  • Building knowledge bases and FAQs
  • Writing README files and project documentation
  • Creating onboarding documentation for developers
Do NOT invoke when:
  • Writing code comments → developer responsibility
  • Creating ADRs → use document-writer
  • Writing marketing content → use content-marketer
  • Designing documentation infrastructure → use documentation-engineer
在以下场景调用此技能：
  • 编写API文档和参考指南
  • 创建用户指南和快速入门教程
  • 搭建知识库和常见问题解答（FAQs）
  • 编写README文件和项目文档
  • 为开发者创建入门培训文档
请勿在以下场景调用：
  • 编写代码注释 → 属于开发者的职责
  • 创建架构决策记录（ADRs）→ 使用document-writer
  • 创作营销内容 → 使用content-marketer
  • 设计文档基础设施 → 使用documentation-engineer

Decision Framework

决策框架

Documentation Type?
├── API Reference → OpenAPI spec + generated docs
├── Getting Started → Quick start guide + first success
├── Conceptual → Architecture overview + mental models
├── How-To → Task-focused step-by-step guides
├── Troubleshooting → Problem-solution format
└── Release Notes → User-focused change descriptions
文档类型？
├── API参考 → OpenAPI规范 + 生成式文档
├── 快速入门 → 快速开始指南 + 首次成功案例
├── 概念性文档 → 架构概述 + 心智模型
├── 操作指南 → 以任务为中心的分步指南
├── 故障排除 → 问题-解决方案格式
└── 发布说明 → 以用户为中心的变更说明

Core Workflows

核心工作流程

1. API Documentation

1. API文档编写

  1. Review API endpoints and data models
  2. Write clear endpoint descriptions with use cases
  3. Document request/response formats with examples
  4. Include authentication and error handling
  5. Add code samples in multiple languages
  6. Test all examples for accuracy
  7. Set up versioning for API changes
  1. 审核API端点和数据模型
  2. 撰写清晰的端点描述及使用案例
  3. 记录请求/响应格式并附带示例
  4. 包含认证和错误处理说明
  5. 添加多语言代码示例
  6. 测试所有示例的准确性
  7. 为API变更设置版本控制

2. Tutorial Development

2. 教程开发

  1. Identify target audience and prerequisites
  2. Define learning objectives and outcomes
  3. Structure content in progressive complexity
  4. Write step-by-step instructions with context
  5. Add code samples that can be copied and run
  6. Include troubleshooting for common issues
  7. Test tutorial flow with fresh environment
  1. 确定目标受众和前置要求
  2. 定义学习目标和成果
  3. 按渐进式复杂度组织内容结构
  4. 撰写带上下文的分步说明
  5. 添加可直接复制运行的代码示例
  6. 包含常见问题的故障排除方案
  7. 在全新环境中测试教程流程

3. Documentation Maintenance

3. 文档维护

  1. Establish documentation review schedule
  2. Set up automated checks for broken links
  3. Track documentation alongside code changes
  4. Collect and incorporate user feedback
  5. Update examples when APIs change
  6. Archive deprecated content appropriately
  7. Monitor analytics for improvement opportunities
  1. 建立文档审核计划
  2. 设置自动化检查以检测失效链接
  3. 随代码变更同步跟踪文档更新
  4. 收集并整合用户反馈
  5. 当API变更时更新示例
  6. 妥善归档已弃用的内容
  7. 监控分析数据以寻找改进机会

Best Practices

最佳实践

  • Write for the reader's goals, not the system's structure
  • Use consistent terminology with a defined glossary
  • Include working code examples that users can copy
  • Test all procedures in clean environments
  • Keep sentences short and paragraphs focused
  • Use visuals (diagrams, screenshots) where they add clarity
  • 围绕读者的目标撰写，而非系统的结构
  • 使用统一术语并定义术语表
  • 包含用户可直接复制的可运行代码示例
  • 在干净环境中测试所有流程
  • 保持句子简短、段落聚焦
  • 在能提升清晰度的地方使用可视化元素（图表、截图）

Anti-Patterns

反模式

  • Developer-centric writing → Focus on user tasks and goals
  • Outdated examples → Automate testing of code samples
  • Wall of text → Use headings, lists, and whitespace
  • Assuming knowledge → State prerequisites explicitly
  • One-time writing → Treat docs as living documents
  • 以开发者为中心的写作 → 应聚焦用户的任务和目标
  • 过时的示例 → 自动化测试代码示例
  • 大段文字堆砌 → 使用标题、列表和留白
  • 假设读者已有相关知识 → 明确说明前置要求
  • 一次性写作 → 将文档视为活的、需要持续更新的内容