Back to Details

technical-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Writing for Developers

面向开发者的技术写作

This skill provides best practices and templates for writing clear, maintainable internal documentation.
本技能提供编写清晰、可维护的内部文档的最佳实践和模板。

Core Principles

核心原则

  1. Audience Awareness: Write for your teammates (and your future self). Assume they know how to code, but not why this specific code exists.
  2. Active Voice: Use active voice for instructions.
    • Bad: "The server should be started by running..."
    • Good: "Run 
      npm start
      to start the server."
  3. Single Source of Truth: Don't duplicate code logic in comments. Explain why, not what.
  4. Front-Load Context: Put the most important information (what is this? how do I run it?) at the top.
  1. 受众意识：面向你的队友（以及未来的你）编写内容。假设他们懂得如何编码，但不了解这段特定代码存在的原因。
  2. 主动语态：操作说明使用主动语态。
    • 错误示例："The server should be started by running..."
    • 正确示例："Run 
      npm start
      to start the server."
  3. 唯一可信源：不要在注释中重复代码逻辑，解释为什么这么做，而非代码是什么。
  4. 核心信息前置：把最重要的信息（这是什么？我要怎么运行它？）放在最顶部。

Common Artifacts & Templates

常见产出物与模板

1. README.md (Root or Component)

1. README.md（根目录或组件目录）

Every significant directory should have a README.
markdown
undefined
每个重要的目录都应该配备一个README。
markdown
undefined

[Project/Component Name]

[Project/Component Name]

[One-sentence description of what this is].
[One-sentence description of what this is].

Prerequisite

Prerequisite

  • Node.js >= 20
  • [Other dependency]
  • Node.js >= 20
  • [Other dependency]

Quick Start

Quick Start

bash
npm install
npm run dev
bash
npm install
npm run dev

Architecture

Architecture

[Brief explanation of how it works. Diagrams are great.]
[Brief explanation of how it works. Diagrams are great.]

Key Concepts

Key Concepts

  • Concept A: Definition...
  • Concept B: Definition...
undefined
  • Concept A: Definition...
  • Concept B: Definition...
undefined

2. Architecture Decision Record (ADR)

2. 架构决策记录（ADR）

Use for significant technical decisions.
markdown
undefined
用于记录重要的技术决策。
markdown
undefined

[Short Title]

[Short Title]

  • Status: [Proposed | Accepted | Deprecated]
  • Date: YYYY-MM-DD
  • Deciders: [List names]
  • Status: [Proposed | Accepted | Deprecated]
  • Date: YYYY-MM-DD
  • Deciders: [List names]

Context

Context

[Describe the problem and constraints.]
[Describe the problem and constraints.]

Decision

Decision

[Describe what we are doing.]
[Describe what we are doing.]

Consequences

Consequences

  • [Positive consequence]
  • [Negative consequence / Trade-off]
undefined
  • [Positive consequence]
  • [Negative consequence / Trade-off]
undefined

Style Guide

风格指南

  • Headers: Use Sentence case for headers (e.g., "Getting started" not "Getting Started").
  • Code Blocks: Always specify the language for syntax highlighting (e.g., ```typescript).
  • Lists: Use bullet points for options, numbered lists for steps.
  • Links: Use relative links 
    [Link](./path/to/file)
    so they work in the repo browser.
  • 标题：标题使用句首大写格式（例如 "Getting started" 而非 "Getting Started"）。
  • 代码块：始终指定代码语言以启用语法高亮（例如 ```typescript）。
  • 列表：选项使用无序列表，步骤使用有序列表。
  • 链接：使用相对链接 
    [Link](./path/to/file)
    确保在仓库浏览器中可以正常访问。

Review Checklist

审核清单

Before committing documentation:
  • Completeness: did I cover "how to run" and "how to test"?
  • Freshness: Did I actually run the commands in a fresh terminal?
  • Links: Do all internal links work?
  • Grammar: Is it readable? (Use a spell checker).
提交文档前请检查：
  • 完整性：我是否涵盖了“如何运行”和“如何测试”的内容？
  • 时效性：我是否真的在全新终端中运行过文档中的所有命令？
  • 链接：所有内部链接都可以正常跳转吗？
  • 语法：内容是否通顺易读？（建议使用拼写检查工具）