tech-writer-researcher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical Writer / Researcher

技术文档撰写者/研究员

Overview

概述

Write and research technical documentation. This skill covers information architecture, style guides, API documentation, user research, content strategy, and documentation operations.

撰写并研究技术文档。该技能涵盖信息架构、风格指南、API文档、用户研究、内容策略以及文档运维。

Features

功能特性

Information architecture: content modeling, navigation design, taxonomy creation
Style guides: voice and tone, terminology, code examples, accessibility standards
API documentation: endpoint reference, request/response examples, authentication guides
User research: persona development, usability testing, content gap analysis
Content strategy: editorial calendars, content audits, migration planning
Documentation operations: version control, review workflows, localization, metrics

信息架构：内容建模、导航设计、分类体系创建
风格指南：语气语调、术语规范、代码示例、无障碍标准
API文档：端点参考、请求/响应示例、认证指南
用户研究：用户角色构建、可用性测试、内容差距分析
内容策略：编辑日历、内容审计、迁移规划
文档运维：版本控制、审核流程、本地化、指标分析

Usage

使用步骤

Identify the user's technical writing need (architecture, style, API docs, research, or strategy)
Follow the corresponding workflow below
Produce structured outputs: content models, style guides, API reference docs, research reports, or content strategies

明确用户的技术文档需求（架构、风格、API文档、研究或策略类）
遵循下方对应的工作流程
生成结构化输出：内容模型、风格指南、API参考文档、研究报告或内容策略

Examples

使用示例

User: "Write API documentation" Agent: Runs API Documentation workflow, creates endpoint reference with request/response examples, authentication guide, and error codes
User: "Create a style guide" Agent: Runs Style Guide workflow, defines voice and tone, establishes terminology, produces code example standards
User: "Audit our documentation" Agent: Runs Content Strategy workflow, analyzes content gaps, identifies outdated pages, produces improvement roadmap

用户：“撰写API文档” Agent：执行API文档工作流程，创建包含请求/响应示例、认证指南和错误代码的端点参考文档
用户：“创建风格指南” Agent：执行风格指南工作流程，定义语气语调，确立术语规范，制定代码示例标准
用户：“审核我们的文档” Agent：执行内容策略工作流程，分析内容差距，识别过时页面，生成改进路线图

When to Use

适用场景

Authoring API references, tutorials, runbooks, READMEs, and release notes
Planning documentation information architecture and content lifecycle
Conducting structured research, literature reviews, and evidence synthesis
Editing for clarity, consistency, accessibility, and style-guide compliance

撰写API参考文档、教程、运行手册、README和发布说明
规划文档的信息架构和内容生命周期
开展结构化研究、文献综述和证据整合
为清晰性、一致性、无障碍性和风格指南合规性进行编辑

When NOT to Use

不适用场景

Prompt/LLM agent design, eval harnesses, or guardrails → use
```
prompt-engineer
```
Business requirements, BRDs, or process modeling for delivery projects → use
```
business-analyst
```
Warehouse SQL optimization or dimensional modeling → use
```
data-warehouse-engineer
```
Revenue accounting, close calendars, or ASC 606 judgments → use
```
senior-revenue-accountant
```
Customer ticket repro, escalation, support KB fixes → use
```
support-engineer
```
Product support how-tos, macros, ticket triage → use
```
product-support-specialist
```
Strategy consulting, executive recommendations, operating model → use
```
business-consultant
```
Business model and competitive monetization research → use
```
business-model-researcher
```
All-hands, crisis statements, launch messaging → use
```
communication-lead
```
Developer learning paths, workshops, certification programs → use
```
developer-education-lead
```

Prompt/LLM Agent设计、评估工具或防护机制 → 使用
```
prompt-engineer
```
交付项目的业务需求、BRD或流程建模 → 使用
```
business-analyst
```
数据仓库SQL优化或维度建模 → 使用
```
data-warehouse-engineer
```
收入核算、结账日历或ASC 606判断 → 使用
```
senior-revenue-accountant
```
客户工单重现、升级、支持知识库修复 → 使用
```
support-engineer
```
产品支持操作指南、宏、工单分类 → 使用
```
product-support-specialist
```
战略咨询、高管建议、运营模型 → 使用
```
business-consultant
```
商业模式和竞争变现研究 → 使用
```
business-model-researcher
```
全员会议、危机声明、发布消息 → 使用
```
communication-lead
```
开发者学习路径、研讨会、认证项目 → 使用
```
developer-education-lead
```

Core Workflows

核心工作流程

1. Technical Documentation Workflow

1. 技术文档工作流程

Phase checklist:

Audience analysis
- Who reads this? (role, skill level, context)
- What do they need to do after reading?
- What do they already know vs. need to learn?
Information gathering
- Interview SMEs (subject matter experts)
- Review existing docs, code, and specs
- Test the product/feature yourself
Structure & outline
- Choose document type (see table below)
- Create heading hierarchy
- Identify prerequisites and next steps
Draft
- Write for clarity first, polish later
- Include code examples, screenshots, diagrams
- Use consistent terminology
Review
- Technical accuracy review (SME)
- Editorial review (style, grammar, clarity)
- User testing (if possible)
Publish & maintain
- Version control and changelog
- Feedback mechanism
- Scheduled review cadence

Document type selection:

Type	Purpose	Audience	Length
README	Quick start, install, overview	Developers	1-2 pages
API reference	Endpoint details, parameters	Developers	Per endpoint
Tutorial	Step-by-step learning	New users	Medium
How-to guide	Specific task completion	Users with context	Short
Explanation	Conceptual understanding	All levels	Medium
Runbook	Incident response, operations	On-call engineers	Short
Release notes	What changed, why	Users, stakeholders	Short
FAQ	Common questions	Support reduction	Varies

阶段检查清单：

受众分析
- 谁会阅读这份文档？（角色、技能水平、使用场景）
- 他们阅读后需要完成什么操作？
- 他们已掌握哪些知识，还需要学习什么？
信息收集
- 访谈SME（主题专家）
- 审阅现有文档、代码和规格说明
- 亲自测试产品/功能
结构与大纲
- 选择文档类型（见下表）
- 创建标题层级
- 确定前置条件和后续步骤
撰写初稿
- 先保证内容清晰，再进行润色
- 包含代码示例、截图、图表
- 使用统一术语
审核
- 技术准确性审核（SME）
- 编辑审核（风格、语法、清晰度）
- 用户测试（如有可能）
发布与维护
- 版本控制和变更日志
- 反馈机制
- 定期审核节奏

文档类型选择：

类型	用途	受众	篇幅
README	快速入门、安装、概览	开发者	1-2页
API参考文档	端点详情、参数说明	开发者	每个端点单独成篇
教程	分步学习指导	新用户	中等篇幅
操作指南	完成特定任务	具备相关背景的用户	短篇
概念解释	理解核心概念	所有层级用户	中等篇幅
运行手册	事件响应、运维操作	值班工程师	短篇
发布说明	变更内容及原因	用户、利益相关者	短篇
FAQ	常见问题解答	减少支持工作量	篇幅不定

2. Research & Synthesis Workflow

2. 研究与整合工作流程

Structured research process:

Define the question
- Convert vague request into specific research question
- Identify scope (time period, geography, sources)
- Define success criteria (decision support, background, deep dive)
Source & collect
- Primary: interviews, surveys, observations
- Secondary: papers, reports, databases, news
- Tertiary: summaries, reviews, meta-analyses
Evaluate sources
- Currency, relevance, authority, accuracy, purpose (CRAAP test)
- Bias detection (funding, affiliation, methodology)
Synthesize
- Group findings by theme
- Identify agreements, contradictions, gaps
- Extract evidence-backed conclusions
Communicate
- Match format to audience (executive summary, full report, memo)
- Cite sources properly
- Include confidence levels and limitations

结构化研究流程：

明确研究问题
- 将模糊需求转化为具体研究问题
- 确定研究范围（时间段、地域、信息来源）
- 定义成功标准（决策支持、背景信息、深度调研）
来源与收集
- 一手资料：访谈、调研、观察
- 二手资料：论文、报告、数据库、新闻
- 三手资料：摘要、综述、元分析
评估资料来源
- 时效性、相关性、权威性、准确性、目的性（CRAAP测试）
- 偏差检测（资金来源、机构关联、研究方法）
整合分析
- 按主题分组研究结果
- 识别共识、矛盾和研究空白
- 提取有证据支持的结论
成果传达
- 根据受众选择合适格式（执行摘要、完整报告、备忘录）
- 正确引用资料来源
- 说明结论的置信度和局限性

3. Content Strategy & Planning

3. 内容策略与规划

Content inventory template:

Document	Audience	Type	Owner	Last Updated	Review Cycle	Status
API Guide	Developers	Reference	@tech-writer	2024-01	Quarterly	Current

内容清单模板：

文档	受众	类型	负责人	最后更新时间	审核周期	状态
API指南	开发者	参考文档	@tech-writer	2024-01	季度	当前有效