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

核心原则

Audience Awareness: Write for your teammates (and your future self). Assume they know how to code, but not why this specific code exists.
Active Voice: Use active voice for instructions.
- Bad: "The server should be started by running..."
- Good: "Run
```
npm start
```
  to start the server."
Single Source of Truth: Don't duplicate code logic in comments. Explain why, not what.
Front-Load Context: Put the most important information (what is this? how do I run it?) at the top.

受众意识：面向你的队友（以及未来的你）编写内容。假设他们懂得如何编码，但不了解这段特定代码存在的原因。
主动语态：操作说明使用主动语态。
- 错误示例："The server should be started by running..."
- 正确示例："Run
```
npm start
```
  to start the server."
唯一可信源：不要在注释中重复代码逻辑，解释为什么这么做，而非代码是什么。
核心信息前置：把最重要的信息（这是什么？我要怎么运行它？）放在最顶部。

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]

[One-sentence description of what this is].

Prerequisite

Node.js >= 20
[Other dependency]

Node.js >= 20
[Other dependency]

Quick Start

bash

npm install
npm run dev

bash

npm install
npm run dev

Architecture

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

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]

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

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

Context

[Describe the problem and constraints.]

Decision

[Describe what we are doing.]

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).

提交文档前请检查：

完整性：我是否涵盖了“如何运行”和“如何测试”的内容？
时效性：我是否真的在全新终端中运行过文档中的所有命令？
链接：所有内部链接都可以正常跳转吗？
语法：内容是否通顺易读？（建议使用拼写检查工具）