technical-writing
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTechnical Writing
技术写作
<default_to_action>
When writing technical content:
- LEAD with value (what will reader learn/gain?)
- SHOW, don't tell (specific examples, code, numbers)
- STRUCTURE for scanning (headers, bold, short paragraphs)
- CUT ruthlessly (every sentence must earn its place)
- BE honest about trade-offs
Blog Post Structure:
markdown
undefined<default_to_action>
撰写技术内容时：
- 以价值开篇（读者能学到/获得什么？）
- 用实例说话，而非空泛陈述（具体示例、代码、数据）
- 为便于浏览构建结构（标题、加粗、短段落）
- 果断删减冗余内容（每句话都要有存在的意义）
- 坦诚说明利弊取舍
博客文章结构：
markdown
undefinedTitle (specific promise)
标题（明确的价值承诺）
Opening (2-3 paragraphs)
开篇（2-3段）
- Hook: The problem or insight
- Context: Why this matters
- Promise: What they'll learn
- 钩子：提出问题或独到见解
- 背景：说明重要性
- 承诺：告知读者能学到什么
Body (3-5 sections)
正文（3-5个小节）
- One clear idea per section
- Support with examples/code/data
- 每小节聚焦一个清晰观点
- 用示例/代码/数据支撑内容
Closing
结尾
- Key takeaway (1-2 sentences)
- Action reader can take
**Before/After:**
❌ "We implemented a comprehensive testing strategy..."
✅ "We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement."
</default_to_action>- 核心要点（1-2句话）
- 读者可采取的行动
**反面/正面示例：**
❌ "我们实施了一套全面的测试策略..."
✅ "我们将探索性测试纳入迭代规划。现在QE在需求细化阶段与开发人员结对工作。"
</default_to_action>Quick Reference Card
快速参考卡片
Core Principles
核心原则
| Principle | Bad | Good |
|---|---|---|
| Lead with value | "In today's landscape..." | "Here's how we cut bugs 60%" |
| Show, don't tell | "We improved testing" | "Bug detection: 12→47 per sprint" |
| Be specific | "Performance improved" | "Response time: 2.3s→180ms" |
| Honest trade-offs | "This approach is best" | "TDD slowed velocity 20%, reduced bugs 75%" |
| 原则 | 反面示例 | 正面示例 |
|---|---|---|
| 以价值开篇 | "在当今环境下..." | "这是我们将bug减少60%的方法" |
| 用实例说话 | "我们改进了测试流程" | "Bug检测量：从每个迭代12个提升至47个" |
| 内容具体化 | "性能有所提升" | "响应时间：从2.3秒缩短至180毫秒" |
| 坦诚利弊取舍 | "这种方法是最佳选择" | "TDD使开发速度降低20%，但将bug减少了75%" |
Words to Cut
需删减的词汇
| Kill | Reason |
|---|---|
| basically, actually, probably | Hedge words |
| leverage, synergy, paradigm | Corporate speak |
| very, really, quite | Unnecessary qualifiers |
| it should be noted that | Just note it |
| 需删除词汇 | 原因 |
|---|---|
| basically, actually, probably | 模棱两可的措辞 |
| leverage, synergy, paradigm | 企业套话 |
| very, really, quite | 多余的修饰词 |
| it should be noted that | 直接陈述即可 |
Audience-Specific Writing
面向特定受众的写作
For Developers
面向开发人员
- Lead with code or concrete problem
- Show implementation details
- Discuss trade-offs and alternatives
- Link to repos or examples
- 以代码或具体问题开篇
- 展示实现细节
- 讨论利弊取舍与替代方案
- 链接到代码仓库或示例
For QA/QE
面向QA/QE
- Start with testing challenge
- Show strategy, not just tools
- Include risk assessment
- Provide adaptable heuristics
- 从测试挑战切入
- 展示策略而非仅介绍工具
- 包含风险评估
- 提供可调整的启发式方法
For Leadership
面向管理层
- Open with business impact
- Use metrics that matter
- Connect technical to outcomes
- Keep technical details concise
- 以业务影响开篇
- 使用关键业务指标
- 将技术内容与业务成果关联
- 精简技术细节
Editing Checklist
编辑检查清单
Before publishing:
- Title promises something specific
- Opening hooks in 30 seconds
- Claims backed by examples
- All unnecessary words cut
- Code examples tested and correct
- Takeaway crystal clear
- Would send to respected colleague
发布前检查：
- 标题做出明确的价值承诺
- 开篇30秒内抓住读者注意力
- 所有主张均有示例支撑
- 删除所有冗余词汇
- 代码示例已测试且正确
- 核心要点清晰明确
- 愿意分享给资深同事
Example Transformations
示例转换
Before:
"We decided to implement a more comprehensive testing strategy that would allow us to catch bugs earlier in the development lifecycle."
After:
"We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement, identifying risks before code is written."
Before:
"The benefits of this approach are numerous and include improved quality, faster feedback loops, and better team collaboration."
After:
"Three outcomes: bugs found 2 days earlier on average, 30% fewer regression issues, and devs now ask QE for input during design."
反面示例：
"我们决定实施一套更全面的测试策略，以便在开发生命周期早期发现bug。"
正面示例：
"我们将探索性测试纳入迭代规划。现在QE在需求细化阶段与开发人员结对，在代码编写前识别风险。"
反面示例：
"这种方法的好处很多，包括提高质量、加快反馈循环以及改善团队协作。"
正面示例：
"三个成果：平均提前2天发现bug，回归问题减少30%，开发人员现在在设计阶段就会征求QE的意见。"
Agent Integration
Agent集成
typescript
// Generate documentation from code
const docs = await Task("Generate Docs", {
source: 'src/services/PaymentService.ts',
format: 'markdown',
includeExamples: true
}, "qe-quality-analyzer");
// Review documentation quality
const review = await Task("Review Docs", {
files: ['README.md', 'docs/api.md'],
checkClarity: true,
checkCodeExamples: true
}, "qe-quality-analyzer");typescript
// 从代码生成文档
const docs = await Task("Generate Docs", {
source: 'src/services/PaymentService.ts',
format: 'markdown',
includeExamples: true
}, "qe-quality-analyzer");
// 评审文档质量
const review = await Task("Review Docs", {
files: ['README.md', 'docs/api.md'],
checkClarity: true,
checkCodeExamples: true
}, "qe-quality-analyzer");Agent Coordination Hints
Agent协作提示
Memory Namespace
内存命名空间
aqe/technical-writing/
├── generated-docs/* - Auto-generated documentation
├── reviews/* - Documentation review findings
└── templates/* - Reusable doc templatesaqe/technical-writing/
├── generated-docs/* - 自动生成的文档
├── reviews/* - 文档评审结果
└── templates/* - 可复用的文档模板Fleet Coordination
集群协作
typescript
const docsFleet = await FleetManager.coordinate({
strategy: 'documentation',
agents: [
'qe-quality-analyzer', // Generate and review
'qe-api-contract-validator' // API doc accuracy
],
topology: 'sequential'
});typescript
const docsFleet = await FleetManager.coordinate({
strategy: 'documentation',
agents: [
'qe-quality-analyzer', // 生成与评审文档
'qe-api-contract-validator' // 验证API文档准确性
],
topology: 'sequential'
});Related Skills
相关技能
- bug-reporting-excellence - Technical bug writing
- code-review-quality - Review documentation
- bug-reporting-excellence - 技术bug撰写
- code-review-quality - 文档评审
Remember
谨记
You're not writing to impress. You're writing to help people solve problems you've already solved. Be the colleague you wish you'd had.
Write from experience. Only write about what you've done in production. If exploring, say so.
写作不是为了炫技。 你写作是为了帮助人们解决你已经解决过的问题。做你希望拥有的那种同事。
结合经验写作。 只写你在生产环境中实践过的内容。如果是探索性内容，请明确说明。