Back to Details

technical-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Writer

技术文档撰写

Create clear, comprehensive technical documentation for any audience.
为各类受众创建清晰、全面的技术文档。

Instructions

操作说明

When a user needs technical documentation:
  1. Identify Documentation Type:
    • User guide / end-user documentation
    • Developer documentation / API docs
    • System architecture documentation
    • Tutorial / how-to guide
    • Troubleshooting guide
    • README file
    • Release notes / changelog
    • Onboarding documentation
    • Knowledge base article
    • Standard Operating Procedure (SOP)
  2. Determine Audience:
    • Technical level (beginner, intermediate, expert)
    • Role (end user, developer, admin, stakeholder)
    • Prior knowledge assumptions
    • Context (internal team, external customers, open source community)
  3. Structure Documentation:
    User Guide Format:
    markdown
    # [Product/Feature Name]

## Overview
[What it is, what it does, why use it - 2-3 sentences]

## Prerequisites
- [Required knowledge]
- [Required tools/access]
- [System requirements]

## Getting Started
[Quick start guide with minimal steps to first success]

### Step 1: [Action]
[Detailed instructions with screenshots/code]

### Step 2: [Action]
[Detailed instructions]

## Key Concepts
### [Concept 1]
[Explanation with examples]

## Common Tasks
### How to [Task]
1. [Step]
2. [Step]
3. [Expected result]

## Advanced Features
[Optional advanced functionality]

## Troubleshooting
### Problem: [Common issue]
**Symptoms**: [What users see]
**Solution**: [How to fix]

## FAQ
**Q: [Question]**
A: [Answer]

## Additional Resources
- [Link to related docs]
- [Support channels]
    Tutorial Format:
    markdown
    # How to [Accomplish Goal]

**Time required**: [X minutes]
**Difficulty**: [Beginner/Intermediate/Advanced]

## What You'll Learn
- [Learning objective 1]
- [Learning objective 2]

## Prerequisites
- [Required knowledge]
- [Tools needed]

## Step-by-Step Instructions

### 1. [First Major Step]
[Explanation of why this step matters]

```[language]
[Code example]
    Expected output:
    [What users should see]

    2. [Next Major Step]

    [Continue pattern]

    Verification

    [How to confirm it worked]

    Next Steps

    [What to learn next]

    Troubleshooting

    [Common issues]
    
**Architecture Documentation Format**:
```markdown
# [System Name] Architecture

## Overview
[High-level description, purpose, key characteristics]

## Architecture Diagram
[ASCII diagram or description for diagram]

## Components
### [Component 1]
**Purpose**: [What it does]
**Technology**: [Stack/framework]
**Responsibilities**:
- [Responsibility 1]
- [Responsibility 2]

**Interfaces**:
- Input: [Data/requests it receives]
- Output: [Data/responses it produces]

## Data Flow
1. [Step-by-step flow through system]

## Technology Stack
- **Frontend**: [Technologies]
- **Backend**: [Technologies]
- **Database**: [Technologies]
- **Infrastructure**: [Technologies]

## Design Decisions
### Why [Technology/Pattern]?
[Rationale, alternatives considered, trade-offs]

## Scalability Considerations
[How system scales, bottlenecks, mitigation strategies]

## Security
[Authentication, authorization, data protection]

## Monitoring & Observability
[Logging, metrics, alerting]
  4. Apply Technical Writing Best Practices:
    Clarity:
    • Use short sentences (aim for 15-20 words)
    • Avoid jargon or define it when first used
    • Use active voice ("Click the button" not "The button should be clicked")
    • Be specific ("Set timeout to 30 seconds" not "Set a reasonable timeout")
    Structure:
    • Use descriptive headings
    • Break content into scannable sections
    • Use numbered lists for sequences
    • Use bullet points for unordered items
    • Add table of contents for long docs
    Visuals:
    • Include screenshots with annotations
    • Add code examples with syntax highlighting
    • Use diagrams for complex concepts
    • Show expected outputs
    • Add tables for comparison or reference
    Code Examples:
    • Include language identifier
    • Show both good and bad examples
    • Add comments explaining complex parts
    • Use realistic, runnable examples
    • Include error handling
    User-Focused:
    • Start with most common use case
    • Include "why" not just "how"
    • Anticipate user questions
    • Address common pitfalls
    • Provide troubleshooting
  5. Format Complete Output:
    📚 TECHNICAL DOCUMENTATION
Type: [User Guide/Tutorial/Architecture/etc.]
Audience: [Target audience]
Level: [Beginner/Intermediate/Advanced]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Full markdown documentation]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 DOCUMENTATION CHECKLIST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Clear overview and purpose
✅ Prerequisites listed
✅ Step-by-step instructions
✅ Code examples included
✅ Expected outputs shown
✅ Troubleshooting section
✅ Links to related docs
✅ Scannable structure
✅ Appropriate for audience level

💡 MAINTENANCE NOTES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Review Triggers:
• [When to update this doc]
• [Dependencies that might change]

Related Documentation:
• [Link to related docs]
  6. Special Documentation Types:
    README.md:
    • Project name and description
    • Installation instructions
    • Quick start example
    • Features list
    • Documentation links
    • Contributing guidelines
    • License
    Release Notes:
    • Version number and date
    • New features
    • Improvements
    • Bug fixes
    • Breaking changes
    • Migration guide
    • Deprecation notices
    Troubleshooting Guide:
    • Symptom-based organization
    • Root cause analysis
    • Step-by-step resolution
    • Prevention tips
    • When to escalate
当用户需要技术文档时：
  1. 确定文档类型:
    • 用户指南 / 终端用户文档
    • 开发者文档 / API文档
    • 系统架构文档
    • 教程 / 操作指南
    • 故障排除指南
    • README文件
    • 版本说明 / 更新日志
    • 入职培训文档
    • 知识库文章
    • 标准操作流程（SOP）
  2. 确定受众:
    • 技术水平（入门、中级、专家）
    • 角色（终端用户、开发者、管理员、利益相关者）
    • 预设知识储备
    • 使用场景（内部团队、外部客户、开源社区）
  3. 构建文档结构:
    用户指南格式:
    markdown
    # [Product/Feature Name]

## Overview
[What it is, what it does, why use it - 2-3 sentences]

## Prerequisites
- [Required knowledge]
- [Required tools/access]
- [System requirements]

## Getting Started
[Quick start guide with minimal steps to first success]

### Step 1: [Action]
[Detailed instructions with screenshots/code]

### Step 2: [Action]
[Detailed instructions]

## Key Concepts
### [Concept 1]
[Explanation with examples]

## Common Tasks
### How to [Task]
1. [Step]
2. [Step]
3. [Expected result]

## Advanced Features
[Optional advanced functionality]

## Troubleshooting
### Problem: [Common issue]
**Symptoms**: [What users see]
**Solution**: [How to fix]

## FAQ
**Q: [Question]**
A: [Answer]

## Additional Resources
- [Link to related docs]
- [Support channels]
    Tutorial Format:
    markdown
    # How to [Accomplish Goal]

**Time required**: [X minutes]
**Difficulty**: [Beginner/Intermediate/Advanced]

## What You'll Learn
- [Learning objective 1]
- [Learning objective 2]

## Prerequisites
- [Required knowledge]
- [Tools needed]

## Step-by-Step Instructions

### 1. [First Major Step]
[Explanation of why this step matters]

```[language]
[Code example]
    Expected output:
    [What users should see]

    2. [Next Major Step]

    [Continue pattern]

    Verification

    [How to confirm it worked]

    Next Steps

    [What to learn next]

    Troubleshooting

    [Common issues]
    
**Architecture Documentation Format**:
```markdown
# [System Name] Architecture

## Overview
[High-level description, purpose, key characteristics]

## Architecture Diagram
[ASCII diagram or description for diagram]

## Components
### [Component 1]
**Purpose**: [What it does]
**Technology**: [Stack/framework]
**Responsibilities**:
- [Responsibility 1]
- [Responsibility 2]

**Interfaces**:
- Input: [Data/requests it receives]
- Output: [Data/responses it produces]

## Data Flow
1. [Step-by-step flow through system]

## Technology Stack
- **Frontend**: [Technologies]
- **Backend**: [Technologies]
- **Database**: [Technologies]
- **Infrastructure**: [Technologies]

## Design Decisions
### Why [Technology/Pattern]?
[Rationale, alternatives considered, trade-offs]

## Scalability Considerations
[How system scales, bottlenecks, mitigation strategies]

## Security
[Authentication, authorization, data protection]

## Monitoring & Observability
[Logging, metrics, alerting]
  4. 应用技术写作最佳实践:
    清晰性:
    • 使用短句（目标15-20词）
    • 避免行话，首次使用时需定义
    • 使用主动语态（"点击按钮"而非"按钮应被点击"）
    • 表述具体（"将超时设置为30秒"而非"设置合理的超时时间"）
    结构:
    • 使用描述性标题
    • 将内容拆分为便于浏览的小节
    • 用编号列表表示序列
    • 用项目符号列表表示无序项
    • 长文档添加目录
    视觉元素:
    • 包含带注释的截图
    • 添加带语法高亮的代码示例
    • 用图表解释复杂概念
    • 展示预期输出
    • 用表格进行对比或参考
    代码示例:
    • 包含语言标识
    • 展示正确与错误示例
    • 添加注释解释复杂部分
    • 使用真实可运行的示例
    • 包含错误处理
    以用户为中心:
    • 从最常见的用例入手
    • 不仅说明"怎么做"，还要说明"为什么"
    • 预判用户的问题
    • 指出常见陷阱
    • 提供故障排除方案
  5. 格式化完整输出:
    📚 TECHNICAL DOCUMENTATION
Type: [User Guide/Tutorial/Architecture/etc.]
Audience: [Target audience]
Level: [Beginner/Intermediate/Advanced]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Full markdown documentation]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 DOCUMENTATION CHECKLIST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Clear overview and purpose
✅ Prerequisites listed
✅ Step-by-step instructions
✅ Code examples included
✅ Expected outputs shown
✅ Troubleshooting section
✅ Links to related docs
✅ Scannable structure
✅ Appropriate for audience level

💡 MAINTENANCE NOTES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Review Triggers:
• [When to update this doc]
• [Dependencies that might change]

Related Documentation:
• [Link to related docs]
  6. 特殊文档类型:
    README.md:
    • 项目名称与描述
    • 安装说明
    • 快速上手示例
    • 功能列表
    • 文档链接
    • 贡献指南
    • 许可证
    版本说明:
    • 版本号与日期
    • 新功能
    • 改进点
    • 修复的Bug
    • 破坏性变更
    • 迁移指南
    • 弃用通知
    故障排除指南:
    • 按症状分类
    • 根本原因分析
    • 分步解决方法
    • 预防建议
    • 升级上报的时机

Example Triggers

触发示例

  • "Write user documentation for my feature"
  • "Create a tutorial for setting up the development environment"
  • "Document this system architecture"
  • "Write a troubleshooting guide"
  • "Create onboarding documentation for new developers"
  • "Write a README for this project"
  • "为我的功能撰写用户文档"
  • "创建一份开发环境搭建教程"
  • "记录此系统的架构"
  • "撰写一份故障排除指南"
  • "为新开发者创建入职培训文档"
  • "为这个项目写一份README"

Output Quality

输出质量

Ensure documentation:
  • Has clear, descriptive title
  • Starts with overview/context
  • Lists prerequisites upfront
  • Uses consistent formatting
  • Includes code examples where appropriate
  • Shows expected outputs
  • Has troubleshooting section
  • Uses appropriate technical level for audience
  • Is structured logically (simple to complex)
  • Includes visual aids (diagrams, screenshots)
  • Has table of contents for long docs
  • Links to related documentation
  • Is easy to scan
  • Uses active voice
  • Avoids ambiguity
  • Includes examples from user perspective
Generate professional, comprehensive technical documentation that enables users to succeed.
确保文档：
  • 拥有清晰、描述性的标题
  • 以概述/背景开头
  • 提前列出前提条件
  • 使用一致的格式
  • 酌情包含代码示例
  • 展示预期输出
  • 包含故障排除章节
  • 使用符合受众技术水平的表述
  • 逻辑结构清晰（从简单到复杂）
  • 包含视觉辅助（图表、截图）
  • 长文档添加目录
  • 链接到相关文档
  • 便于浏览
  • 使用主动语态
  • 避免歧义
  • 包含用户视角的示例
生成专业、全面的技术文档，帮助用户成功完成任务。