Back to Details

technical-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Writer

技术文档工程师

Expert technical documentation specialist focusing on developer documentation, API references, system architecture docs, runbooks, and knowledge base articles.
专注于开发者文档、API参考手册、系统架构文档、运行手册和知识库文章的专业技术文档专家。

Quick Start

快速开始

  1. Identify doc type using Diátaxis: Tutorial, How-to, Explanation, or Reference
  2. Know your audience - what they know, what they need to accomplish
  3. Start with structure - outline before writing, use templates
  4. Include working examples - all code must be tested and runnable
  5. Add troubleshooting - anticipate common problems
  6. Validate completeness - links work, steps accurate, nothing assumed
  1. 使用Diátaxis框架确定文档类型：教程（Tutorial）、操作指南（How-to）、说明文档（Explanation）或参考手册（Reference）
  2. 了解目标受众 - 他们已掌握的知识、需要完成的任务
  3. 从结构入手 - 先列大纲再写作，使用模板
  4. 包含可运行示例 - 所有代码必须经过测试且可运行
  5. 添加故障排除内容 - 预判常见问题
  6. 验证内容完整性 - 链接可用、步骤准确、无默认假设

Core Capabilities

核心能力

Doc TypePurposeKey Characteristics
TutorialsLearning-orientedHands-on, step-by-step introduction
How-to GuidesTask-orientedSolve specific problems
ExplanationsUnderstanding-orientedBackground, context, concepts
ReferencesInformation-orientedAccurate, complete, searchable
文档类型用途核心特征
教程（Tutorials）以学习为导向实操性、分步式入门
操作指南（How-to Guides）以任务为导向解决特定问题
说明文档（Explanations）以理解为导向背景信息、上下文、概念解析
参考手册（References）以信息查询为导向准确、完整、可检索

Diátaxis Framework

Diátaxis框架

              PRACTICAL                    THEORETICAL
        ┌──────────────────────┬──────────────────────┐
LEARNING│     TUTORIALS        │    EXPLANATIONS      │
        │  "Learning by doing" │  "Understanding why" │
        ├──────────────────────┼──────────────────────┤
WORKING │    HOW-TO GUIDES     │     REFERENCE        │
        │  "Solve problems"    │  "Look up facts"     │
        └──────────────────────┴──────────────────────┘
              PRACTICAL                    THEORETICAL
        ┌──────────────────────┬──────────────────────┐
LEARNING│     TUTORIALS        │    EXPLANATIONS      │
        │  "Learning by doing" │  "Understanding why" │
        ├──────────────────────┼──────────────────────┤
WORKING │    HOW-TO GUIDES     │     REFERENCE        │
        │  "Solve problems"    │  "Look up facts"     │
        └──────────────────────┴──────────────────────┘

Reference Templates

参考模板

Complete templates in 
./references/
:
TemplateUse Case
readme-template.md
Project README with all essential sections
adr-template.md
Architecture Decision Records
api-reference-template.md
REST API documentation
runbook-template.md
Operational procedures
./references/
目录下有完整模板：
模板使用场景
readme-template.md
包含所有必要章节的项目README
adr-template.md
架构决策记录（Architecture Decision Records）
api-reference-template.md
REST API文档
runbook-template.md
操作流程手册

Anti-Patterns (10 Critical Mistakes)

反模式（10个关键错误）

1. Wall of Text

1. 文字墙

Symptom: Dense paragraphs, no headings or visual breaks Fix: Headings, bullet points, tables, code blocks, whitespace
症状：段落密集，无标题或视觉分隔 解决方法：使用标题、项目符号、表格、代码块、留白

2. Outdated Examples

2. 示例过时

Symptom: Code samples that don't compile or use deprecated APIs Fix: Test all examples in CI, version-lock dependencies, add "last verified" dates
症状：代码示例无法编译或使用已废弃的API 解决方法：在CI中测试所有示例，锁定依赖版本，添加“最后验证日期”

3. Missing Prerequisites

3. 缺少前置条件

Symptom: Tutorials assume knowledge/setup without stating it Fix: List prerequisites upfront, link to setup guides, specify versions
症状：教程默认用户已掌握某些知识/完成某些设置但未说明 解决方法：提前列出前置条件，链接到设置指南，指定版本信息

4. Expert Blindness

4. 专家盲区

Symptom: Skipping "obvious" steps that aren't obvious to beginners Fix: Have newcomers test docs, include all steps, explain the "why"
症状：跳过对新手而言并不“显而易见”的步骤 解决方法：让新手测试文档，包含所有步骤，解释“为什么要这么做”

5. No Error Guidance

5. 无错误指导

Symptom: Happy path only, no troubleshooting Fix: Include common errors and solutions, link to support channels
症状：仅展示正常流程，无故障排除内容 解决方法：包含常见错误及解决方案，链接到支持渠道

6. Broken Links

6. 链接失效

Symptom: 404s to moved or deleted pages Fix: Link checking in CI, relative links where possible, redirects for moved content
症状：指向已移动或删除页面的404错误 解决方法：在CI中检查链接，尽可能使用相对链接，对已移动内容设置重定向

7. Inconsistent Formatting

7. 格式不一致

Symptom: Different styles, code block languages, heading levels Fix: Style guide, linting (markdownlint), templates for common doc types
症状：样式、代码块语言、标题层级不统一 解决方法：使用风格指南、语法检查工具（如markdownlint）、通用文档模板

8. Missing Context

8. 缺少上下文

Symptom: Docs assume reader knows system architecture Fix: Brief context at top, link to architecture docs, explain "where this fits"
症状：文档默认读者了解系统架构 解决方法：在顶部添加简要上下文，链接到架构文档，说明“本文档的定位”

9. Stale Screenshots

9. 截图过时

Symptom: UI screenshots from 3 versions ago Fix: Automate screenshot capture, note UI version, prefer text over images
症状：使用3个版本前的UI截图 解决方法：自动化截图捕获，标注UI版本，优先使用文字而非图片

10. No Versioning

10. 无版本控制

Symptom: Docs don't match user's installed version Fix: Version selector, version badges, maintain docs per major version
症状：文档与用户安装的版本不匹配 解决方法：添加版本选择器、版本徽章，针对每个主要版本维护文档

Quality Checklist

质量检查清单

Structure:
  • Follows Diátaxis framework (tutorial/how-to/explanation/reference)
  • Appropriate for target audience level
  • Consistent formatting and style
  • Updated table of contents
Content:
  • Code examples are tested and runnable
  • All links work (no 404s)
  • Version information where relevant
  • Includes troubleshooting section
Completeness:
  • Prerequisites listed upfront
  • All steps included (no expert blindness)
  • Error scenarios covered
  • Related documentation linked
结构：
  • 遵循Diátaxis框架（教程/操作指南/说明文档/参考手册）
  • 符合目标受众的知识水平
  • 格式和风格统一
  • 目录已更新
内容：
  • 代码示例经过测试且可运行
  • 所有链接可用（无404错误）
  • 包含相关版本信息
  • 包含故障排除章节
完整性：
  • 提前列出前置条件
  • 包含所有步骤（无专家盲区）
  • 覆盖错误场景
  • 关联相关文档链接

Validation Script

验证脚本

Run 
./scripts/validate-docs.sh
to check:
  • README completeness
  • Documentation structure
  • ADR format compliance
  • Broken links
  • Common documentation issues
运行
./scripts/validate-docs.sh
检查以下内容：
  • README完整性
  • 文档结构
  • ADR格式合规性
  • 失效链接
  • 常见文档问题

Documentation Tools

文档工具

Static Sites: Docusaurus, MkDocs, VitePress, Astro API Docs: Swagger/Redoc, Stoplight, ReadMe.io Diagrams: Mermaid, PlantUML, Excalidraw, Diagrams.net
静态站点：Docusaurus, MkDocs, VitePress, Astro API文档：Swagger/Redoc, Stoplight, ReadMe.io 图表工具：Mermaid, PlantUML, Excalidraw, Diagrams.net

External Resources

外部资源