technical-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Writing

技术文档撰写

When to use this skill

何时使用此技能

  • Writing technical specifications
  • Creating architecture documentation
  • Documenting system designs
  • Writing runbooks and operational guides
  • Creating developer documentation
  • API documentation
  • User manuals and guides
  • Release notes and changelogs
  • 撰写技术规格说明
  • 创建架构文档
  • 记录系统设计
  • 编写运行手册和操作指南
  • 创建开发者文档
  • API文档
  • 用户手册和指南
  • 发布说明和变更日志

Instructions

操作步骤

Step 1: Understand your audience

步骤1:了解你的受众

Developer audience:
  • Focus on implementation details
  • Include code examples
  • Technical terminology is okay
  • Show how, not just what
DevOps/Operations audience:
  • Focus on deployment and maintenance
  • Include configuration examples
  • Emphasize monitoring and troubleshooting
  • Provide runbooks
Manager/Stakeholder audience:
  • High-level overview
  • Business impact
  • Minimal technical jargon
  • Focus on outcomes
End user audience:
  • Simple, clear language
  • Step-by-step instructions
  • Visual aids (screenshots, videos)
  • FAQ section
开发者受众:
  • 聚焦实现细节
  • 包含代码示例
  • 可使用技术术语
  • 展示实现方法,而非仅说明内容
DevOps/运维受众:
  • 聚焦部署和维护
  • 包含配置示例
  • 强调监控和故障排查
  • 提供运行手册
管理者/利益相关者受众:
  • 高层概述
  • 业务影响
  • 尽量减少技术行话
  • 聚焦成果
终端用户受众:
  • 简洁明了的语言
  • 分步式操作说明
  • 视觉辅助(截图、视频)
  • FAQ板块

Step 2: Choose the right document type

步骤2:选择合适的文档类型

Technical Specification:
markdown
undefined
技术规格说明:
markdown
undefined

[Feature Name] Technical Specification

[功能名称] 技术规格说明

Overview

概述

Brief description of what this spec covers
本规格说明涵盖内容的简要描述

Problem Statement

问题陈述

What problem are we solving?
我们要解决什么问题?

Goals and Non-Goals

目标与非目标

Goals

目标

  • Goal 1
  • Goal 2
  • 目标1
  • 目标2

Non-Goals

非目标

  • What we're explicitly not doing
  • 明确不做的内容

Solution Design

解决方案设计

High-Level Architecture

高层架构

Data Models

数据模型

API Contracts

API契约

User Interface

用户界面

Implementation Plan

实施计划

Phase 1

阶段1

Phase 2

阶段2

Testing Strategy

测试策略

Security Considerations

安全考量

Performance Considerations

性能考量

Monitoring and Alerting

监控与告警

Rollout Plan

上线计划

Rollback Plan

回滚计划

Open Questions

待解决问题

References

参考资料


**Architecture Document**:
```markdown

**架构文档**:
```markdown

System Architecture

系统架构

Overview

概述

High-level system description
系统高层描述

Architecture Diagram

架构图

[Insert diagram]
[插入图表]

Components

组件

Component 1

组件1

  • Responsibility
  • Technology stack
  • Interfaces
  • 职责
  • 技术栈
  • 接口

Component 2

组件2

...
...

Data Flow

数据流

How data moves through the system
数据在系统中的流转方式

Key Design Decisions

关键设计决策

Decision 1

决策1

  • Context
  • Options considered
  • Decision made
  • Rationale
  • 背景
  • 考虑的选项
  • 最终决策
  • 决策依据

Technology Stack

技术栈

  • Frontend: React, TypeScript
  • Backend: Python, FastAPI
  • Database: PostgreSQL
  • Infrastructure: AWS, Docker, Kubernetes
  • Frontend: React, TypeScript
  • Backend: Python, FastAPI
  • Database: PostgreSQL
  • Infrastructure: AWS, Docker, Kubernetes

Scalability

可扩展性

How the system scales
系统的扩展方式

Security

安全

Authentication, authorization, data protection
认证、授权、数据保护

Monitoring and Observability

监控与可观测性

Metrics, logs, tracing
指标、日志、追踪

Disaster Recovery

灾难恢复

Backup and recovery procedures
备份与恢复流程

Future Considerations

未来规划


**Runbook**:
```markdown

**运行手册**:
```markdown

[Service Name] Runbook

[服务名称] 运行手册

Service Overview

服务概述

What this service does
本服务的功能

Dependencies

依赖项

  • Service A
  • Service B
  • Database X
  • 服务A
  • 服务B
  • 数据库X

Deployment

部署

How to deploy

部署方式

bash
./deploy.sh production
bash
./deploy.sh production

Rollback

回滚

bash
./rollback.sh
bash
./rollback.sh

Monitoring

监控

Key Metrics

关键指标

  • Request rate
  • Error rate
  • Latency
  • 请求速率
  • 错误率
  • 延迟

Dashboards

仪表盘

  • Production Dashboard
  • Alerts
  • 生产环境仪表盘
  • 告警

Common Issues

常见问题

Issue 1: High latency

问题1:高延迟

Symptoms: Response time > 1s Diagnosis: Check database connection pool Resolution: Restart service or scale up
症状: 响应时间 > 1s 诊断: 检查数据库连接池 解决方法: 重启服务或扩容

Issue 2: Memory leak

问题2:内存泄漏

Symptoms: Memory usage growing over time Diagnosis: Check heap dump Resolution: Restart service, investigate in staging
症状: 内存占用持续增长 诊断: 检查堆转储 解决方法: 重启服务,在预发布环境排查

Troubleshooting

故障排查

How to check logs

如何查看日志

bash
kubectl logs -f deployment/service-name
bash
kubectl logs -f deployment/service-name

How to access metrics

如何获取指标

bash
curl https://api/metrics
bash
curl https://api/metrics

Emergency Contacts

紧急联系人

  • On-call: PagerDuty
  • Team Slack: #team-name

**API Documentation**:
```markdown
  • 值班人员: PagerDuty
  • 团队Slack: #team-name

**API文档**:
```markdown

API Documentation

API文档

Authentication

认证

All requests require authentication:
bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/endpoint
所有请求均需认证:
bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/endpoint

Endpoints

接口

List Users

列出用户

GET /api/v1/users
Parameters:
NameTypeRequiredDescription
pageintegerNoPage number (default: 1)
limitintegerNoItems per page (default: 20)
Example Request:
bash
curl -X GET "https://api.example.com/api/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
Example Response:
json
{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}
Error Responses:
StatusDescription
400Bad Request
401Unauthorized
500Server Error
undefined
GET /api/v1/users
参数:
名称类型是否必填描述
pageinteger页码(默认: 1)
limitinteger每页条目数(默认: 20)
示例请求:
bash
curl -X GET "https://api.example.com/api/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
示例响应:
json
{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}
错误响应:
状态码描述
400错误请求
401未授权
500服务器错误
undefined

Step 3: Writing guidelines

步骤3:撰写指南

Clarity:
  • Use simple, direct language
  • One idea per sentence
  • Short paragraphs (3-5 sentences)
  • Define technical terms
  • Avoid jargon when possible
Structure:
  • Use hierarchical headings (H1, H2, H3)
  • Break content into sections
  • Use lists for multiple items
  • Use tables for structured data
  • Add table of contents for long docs
Examples:
  • Include code examples
  • Provide diagrams
  • Show before/after comparisons
  • Real-world scenarios
Completeness:
  • Cover prerequisites
  • Include error handling
  • Document edge cases
  • Explain why, not just how
  • Link to related docs
Consistency:
  • Consistent terminology
  • Consistent formatting
  • Consistent code style
  • Consistent structure
清晰性:
  • 使用简洁直接的语言
  • 每句表达一个想法
  • 短段落(3-5句)
  • 定义技术术语
  • 尽可能避免行话
结构:
  • 使用层级标题(H1, H2, H3)
  • 将内容划分为多个板块
  • 用列表展示多个条目
  • 用表格展示结构化数据
  • 长文档添加目录
示例:
  • 包含代码示例
  • 提供图表
  • 展示前后对比
  • 真实场景案例
完整性:
  • 涵盖前置条件
  • 包含错误处理
  • 记录边缘情况
  • 解释原因,而非仅说明方法
  • 关联相关文档
一致性:
  • 术语一致
  • 格式一致
  • 代码风格一致
  • 结构一致

Step 4: Visual aids

步骤4:视觉辅助

Architecture diagrams (Mermaid):
mermaid
graph TB
    A[Client] -->|HTTP| B[Load Balancer]
    B --> C[Web Server 1]
    B --> D[Web Server 2]
    C --> E[Database]
    D --> E
Sequence diagrams:
mermaid
sequenceDiagram
    Client->>+Server: Request
    Server->>+Database: Query
    Database-->>-Server: Data
    Server-->>-Client: Response
Flowcharts:
mermaid
flowchart TD
    A[Start] --> B{Is valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
    C --> E[End]
    D --> E
Code blocks with syntax highlighting:
python
def calculate_total(items: List[Item]) -> Decimal:
    """Calculate total price of items."""
    return sum(item.price for item in items)
Screenshots:
  • Use for UI documentation
  • Annotate important parts
  • Keep up-to-date with UI changes
Tables:
ParameterTypeDefaultDescription
timeoutint30Request timeout in seconds
retriesint3Number of retry attempts
架构图 (Mermaid):
mermaid
graph TB
    A[Client] -->|HTTP| B[Load Balancer]
    B --> C[Web Server 1]
    B --> D[Web Server 2]
    C --> E[Database]
    D --> E
时序图:
mermaid
sequenceDiagram
    Client->>+Server: Request
    Server->>+Database: Query
    Database-->>-Server: Data
    Server-->>-Client: Response
流程图:
mermaid
flowchart TD
    A[Start] --> B{Is valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
    C --> E[End]
    D --> E
带语法高亮的代码块:
python
def calculate_total(items: List[Item]) -> Decimal:
    """Calculate total price of items."""
    return sum(item.price for item in items)
截图:
  • 用于UI文档
  • 标注重要部分
  • 随UI变化及时更新
表格:
参数类型默认值描述
timeoutint30请求超时时间(秒)
retriesint3重试次数

Step 5: Review and refine

步骤5:审核与优化

Self-review checklist:
  • Clear purpose stated upfront
  • Logical flow of information
  • All terms defined
  • Code examples tested
  • Links work
  • Diagrams are clear
  • No typos or grammar errors
  • Consistent formatting
  • Table of contents (if needed)
  • Last updated date
Get feedback:
  • Have someone from target audience review
  • Test instructions (can they follow them?)
  • Check for missing information
  • Verify accuracy
Maintain documentation:
  • Update with code changes
  • Version your docs
  • Archive outdated docs
  • Regular review cycle
自我审核清单:
  • 开头明确说明文档目的
  • 信息逻辑连贯
  • 所有术语已定义
  • 代码示例已测试
  • 链接有效
  • 图表清晰
  • 无拼写或语法错误
  • 格式一致
  • 长文档已添加目录
  • 包含最后更新日期
获取反馈:
  • 让目标受众中的人员审核
  • 测试操作说明(他们能否遵循?)
  • 检查是否有信息缺失
  • 验证内容准确性
维护文档:
  • 随代码变更更新文档
  • 为文档版本化
  • 归档过时文档
  • 定期审核

Document templates

文档模板

Technical Spec Template

技术规格说明模板

markdown
undefined
markdown
undefined

[Feature Name] Technical Spec

[功能名称] 技术规格说明

Author: [Your Name] Date: [Date] Status: [Draft/Review/Approved]
作者: [你的姓名] 日期: [日期] 状态: [草稿/审核中/已批准]

Overview

概述

[1-2 paragraphs describing what this document covers]
[1-2段描述本文档涵盖的内容]

Background

背景

[Context and motivation]
[上下文与动机]

Goals

目标

  • Goal 1
  • Goal 2
  • 目标1
  • 目标2

Non-Goals

非目标

  • What we're not doing
  • 不做的内容

Detailed Design

详细设计

[Technical details]
[技术细节]

Alternatives Considered

备选方案考量

[Other approaches and why we didn't choose them]
[其他方案及未选择的原因]

Timeline

时间线

  • Week 1: ...
  • Week 2: ...
  • 第1周: ...
  • 第2周: ...

Open Questions

待解决问题

  • Question 1
  • Question 2
  • 问题1
  • 问题2

Features

功能

  • Feature 1
  • Feature 2
  • 功能1
  • 功能2

Installation

安装

Prerequisites

前置条件

  • Node.js >= 14
  • npm >= 6
  • Node.js >= 14
  • npm >= 6

Setup

设置

bash
git clone https://github.com/user/project.git
cd project
npm install
bash
git clone https://github.com/user/project.git
cd project
npm install

Usage

使用

bash
npm start
bash
npm start

Configuration

配置

Environment variables:
  • API_KEY
    : Your API key
  • PORT
    : Server port (default: 3000)
环境变量:
  • API_KEY
    : 你的API密钥
  • PORT
    : 服务器端口(默认: 3000)

Development

开发

bash
npm run dev
npm test
bash
npm run dev
npm test

Deployment

部署

[Deployment instructions]
[部署说明]

Contributing

贡献

[Contributing guidelines]
[贡献指南]

License

许可证

MIT
undefined
MIT
undefined

Changelog Template

变更日志模板

markdown
undefined
markdown
undefined

Changelog

变更日志

[1.2.0] - 2024-01-15

[1.2.0] - 2024-01-15

Added

新增

  • New feature X
  • Support for Y
  • 新功能X
  • 支持Y

Changed

变更

  • Improved performance of Z
  • Updated dependency A to v2.0
  • 优化Z的性能
  • 将依赖A更新至v2.0

Fixed

修复

  • Bug where user couldn't login
  • Memory leak in background task
  • 用户无法登录的问题
  • 后台任务中的内存泄漏

Deprecated

弃用

  • Old API endpoint /v1/users (use /v2/users)
  • 旧API接口 /v1/users(使用 /v2/users)

Removed

移除

  • Legacy authentication method
  • 旧版认证方式

Security

安全

  • Fixed XSS vulnerability in comments
  • 修复评论中的XSS漏洞

[1.1.0] - 2024-01-01

[1.1.0] - 2024-01-01

...
undefined
...
undefined

Writing tips

撰写技巧

Use active voice

使用主动语态

✅ Good: "The system sends a notification"
❌ Bad: "A notification is sent by the system"
✅ 推荐: "系统发送通知"
❌ 不推荐: "通知由系统发送"

Be concise

简洁明了

✅ Good: "Click Save to save changes"
❌ Bad: "In order to save your changes, you should click on the Save button"
✅ 推荐: "点击保存以更改设置"
❌ 不推荐: "为了保存你的更改,你应该点击保存按钮"

Use examples

使用示例

✅ Good:
"Set the timeout in seconds:
```yaml
timeout: 30
❌ Bad: "Configure the timeout parameter appropriately"
undefined
✅ 推荐:
"设置超时时间(秒):
```yaml
timeout: 30
❌ 不推荐: "合理配置超时参数"
undefined

Break down complexity

拆解复杂内容

✅ Good:
"To deploy:
1. Build the image
2. Push to registry
3. Update deployment
4. Verify rollout"

❌ Bad:
"Deploy by building and pushing the image to the registry, then update
the deployment and verify the rollout succeeded"
✅ 推荐:
"部署步骤:
1. 构建镜像
2. 推送至镜像仓库
3. 更新部署配置
4. 验证上线"

❌ 不推荐:
"通过构建并推送镜像至仓库,然后更新部署配置并验证上线成功来完成部署"

Common mistakes to avoid

需避免的常见错误

  1. Assuming knowledge: Define terms, explain context
  2. Outdated docs: Keep in sync with code
  3. Missing examples: Always include examples
  4. No visuals: Use diagrams for complex concepts
  5. Poor structure: Use headings and sections
  6. Passive voice: Use active voice
  7. Too much jargon: Write for your audience
  8. No version info: Date docs, note versions
  9. Missing error cases: Document what can go wrong
  10. No maintenance: Update regularly
  1. 假设受众已有相关知识: 定义术语,解释上下文
  2. 文档过时: 与代码保持同步
  3. 缺少示例: 始终包含示例
  4. 无视觉辅助: 复杂概念使用图表
  5. 结构混乱: 使用标题和板块
  6. 被动语态: 使用主动语态
  7. 行话过多: 贴合受众水平撰写
  8. 无版本信息: 标注文档日期和版本
  9. 缺少错误场景: 记录可能出现的问题
  10. 无维护: 定期更新

Best practices

最佳实践

  1. Write for your audience: Match their knowledge level
  2. Start with why: Explain the purpose
  3. Show, don't just tell: Use examples
  4. Be consistent: Terminology, style, structure
  5. Test your docs: Can someone follow them?
  6. Version your docs: Track with code versions
  7. Use templates: Consistency across docs
  8. Link related docs: Help readers find more info
  9. Update with code: Docs are part of the code
  10. Review regularly: Quarterly doc review
  1. 为受众撰写: 匹配他们的知识水平
  2. 先说明原因: 解释文档目的
  3. 展示而非仅描述: 使用示例
  4. 保持一致: 术语、风格、结构统一
  5. 测试文档: 他人能否遵循操作?
  6. 文档版本化: 与代码版本同步
  7. 使用模板: 确保文档一致性
  8. 关联相关文档: 帮助读者查找更多信息
  9. 随代码更新: 文档是代码的一部分
  10. 定期审核: 每季度审核文档

Tools

工具

Diagram tools:
  • Mermaid (markdown-based)
  • Draw.io
  • Lucidchart
  • PlantUML
Documentation platforms:
  • GitBook
  • Docusaurus
  • MkDocs
  • Sphinx
Style checkers:
  • Grammarly
  • Hemingway Editor
  • Vale
Screenshot tools:
  • Snagit
  • CloudApp
  • Loom (for videos)
图表工具:
  • Mermaid(基于Markdown)
  • Draw.io
  • Lucidchart
  • PlantUML
文档平台:
  • GitBook
  • Docusaurus
  • MkDocs
  • Sphinx
语法检查工具:
  • Grammarly
  • Hemingway Editor
  • Vale
截图工具:
  • Snagit
  • CloudApp
  • Loom(视频录制)

Examples

示例

Example 1: Basic usage

示例1:基础用法

<!-- Add example content here -->
<!-- 在此添加示例内容 -->

Example 2: Advanced usage

示例2:高级用法

<!-- Add advanced example content here -->
<!-- 在此添加高级示例内容 -->