technical-writing
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTechnical 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
**架构文档**:
```markdownSystem 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 productionbash
./deploy.sh productionRollback
回滚
bash
./rollback.shbash
./rollback.shMonitoring
监控
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-namebash
kubectl logs -f deployment/service-nameHow to access metrics
如何获取指标
bash
curl https://api/metricsbash
curl https://api/metricsEmergency Contacts
紧急联系人
- On-call: PagerDuty
- Team Slack: #team-name
**API Documentation**:
```markdown- 值班人员: PagerDuty
- 团队Slack: #team-name
**API文档**:
```markdownAPI 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/endpointEndpoints
接口
List Users
列出用户
GET /api/v1/usersParameters:
| Name | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Page number (default: 1) |
| limit | integer | No | Items 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:
| Status | Description |
|---|---|
| 400 | Bad Request |
| 401 | Unauthorized |
| 500 | Server Error |
undefinedGET /api/v1/users参数:
| 名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| page | integer | 否 | 页码(默认: 1) |
| limit | integer | 否 | 每页条目数(默认: 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 | 服务器错误 |
undefinedStep 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 --> ESequence diagrams:
mermaid
sequenceDiagram
Client->>+Server: Request
Server->>+Database: Query
Database-->>-Server: Data
Server-->>-Client: ResponseFlowcharts:
mermaid
flowchart TD
A[Start] --> B{Is valid?}
B -->|Yes| C[Process]
B -->|No| D[Error]
C --> E[End]
D --> ECode 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:
| Parameter | Type | Default | Description |
|---|---|---|---|
| timeout | int | 30 | Request timeout in seconds |
| retries | int | 3 | Number 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变化及时更新
表格:
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| timeout | int | 30 | 请求超时时间(秒) |
| retries | int | 3 | 重试次数 |
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
undefinedmarkdown
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 installbash
git clone https://github.com/user/project.git
cd project
npm installUsage
使用
bash
npm startbash
npm startConfiguration
配置
Environment variables:
- : Your API key
API_KEY - : Server port (default: 3000)
PORT
环境变量:
- : 你的API密钥
API_KEY - : 服务器端口(默认: 3000)
PORT
Development
开发
bash
npm run dev
npm testbash
npm run dev
npm testDeployment
部署
[Deployment instructions]
[部署说明]
Contributing
贡献
[Contributing guidelines]
[贡献指南]
License
许可证
MIT
undefinedMIT
undefinedChangelog Template
变更日志模板
markdown
undefinedmarkdown
undefinedChangelog
变更日志
[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...
undefinedWriting 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❌ 不推荐:
"合理配置超时参数"
undefinedBreak 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
需避免的常见错误
- Assuming knowledge: Define terms, explain context
- Outdated docs: Keep in sync with code
- Missing examples: Always include examples
- No visuals: Use diagrams for complex concepts
- Poor structure: Use headings and sections
- Passive voice: Use active voice
- Too much jargon: Write for your audience
- No version info: Date docs, note versions
- Missing error cases: Document what can go wrong
- No maintenance: Update regularly
- 假设受众已有相关知识: 定义术语,解释上下文
- 文档过时: 与代码保持同步
- 缺少示例: 始终包含示例
- 无视觉辅助: 复杂概念使用图表
- 结构混乱: 使用标题和板块
- 被动语态: 使用主动语态
- 行话过多: 贴合受众水平撰写
- 无版本信息: 标注文档日期和版本
- 缺少错误场景: 记录可能出现的问题
- 无维护: 定期更新
Best practices
最佳实践
- Write for your audience: Match their knowledge level
- Start with why: Explain the purpose
- Show, don't just tell: Use examples
- Be consistent: Terminology, style, structure
- Test your docs: Can someone follow them?
- Version your docs: Track with code versions
- Use templates: Consistency across docs
- Link related docs: Help readers find more info
- Update with code: Docs are part of the code
- Review regularly: Quarterly doc review
- 为受众撰写: 匹配他们的知识水平
- 先说明原因: 解释文档目的
- 展示而非仅描述: 使用示例
- 保持一致: 术语、风格、结构统一
- 测试文档: 他人能否遵循操作?
- 文档版本化: 与代码版本同步
- 使用模板: 确保文档一致性
- 关联相关文档: 帮助读者查找更多信息
- 随代码更新: 文档是代码的一部分
- 定期审核: 每季度审核文档
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 -->
<!-- 在此添加高级示例内容 -->