Documentation Writing

技术文档编写

52 rules across 9 categories for documentation quality. Focuses on concrete issues with concrete fixes.

涵盖9大类别、共52条提升文档质量的规则，聚焦具体问题并提供明确修复方案。

Doc Writing/Audit Workflow

文档编写/审核工作流

Copy and track this checklist during the audit:

text

Doc writing/audit progress:
- [ ] Step 1: Determine doc type (tutorial, how-to, reference, explanation) and audience
- [ ] Step 2: Run CRITICAL checks (voice and tone, structure and organization)
- [ ] Step 3: Run HIGH checks (clarity and language, code examples)
- [ ] Step 4: Run MEDIUM+ checks for remaining categories in scope
- [ ] Step 5: Report findings with file:line and concrete fixes

Audit only changed files unless a full sweep is requested.
Identify the doc type (tutorial, how-to, reference, explanation) and intended audience to select relevant categories.
Load rule files progressively by category prefix — read only what applies.
Prioritize CRITICAL and HIGH findings before medium-priority polish.
After fixes, rerun the relevant rules before finalizing.

在审核过程中可复制并跟踪以下检查清单：

text

Doc writing/audit progress:
- [ ] Step 1: Determine doc type (tutorial, how-to, reference, explanation) and audience
- [ ] Step 2: Run CRITICAL checks (voice and tone, structure and organization)
- [ ] Step 3: Run HIGH checks (clarity and language, code examples)
- [ ] Step 4: Run MEDIUM+ checks for remaining categories in scope
- [ ] Step 5: Report findings with file:line and concrete fixes

除非要求全面检查，否则仅审核有变更的文件。
确定文档类型（教程、操作指南、参考文档、说明文档）及目标受众，以选择相关类别。
按类别前缀逐步加载规则文件——仅阅读适用内容。
优先处理CRITICAL（关键）和HIGH（高优先级）问题，再进行中等优先级的优化。
修复完成后，在最终定稿前重新运行相关规则检查。

Rule Categories by Priority

按优先级划分的规则类别


voice-
structure-
clarity-
code-
format-
nav-
scan-
hygiene-
review-

Priority	Category	Impact	Prefix	Rules
1	Voice & Tone	CRITICAL	`voice-`	4
2	Structure & Organization	CRITICAL	`structure-`	10
3	Clarity & Language	HIGH	`clarity-`	6
4	Code Examples	HIGH	`code-`	7
5	Formatting & Syntax	MEDIUM-HIGH	`format-`	8
6	Navigation & Linking	MEDIUM-HIGH	`nav-`	6
7	Scanability & Readability	MEDIUM	`scan-`	2
8	Content Hygiene	MEDIUM	`hygiene-`	6
9	Review & Testing	LOW-MEDIUM	`review-`	3


voice-
structure-
clarity-
code-
format-
nav-
scan-
hygiene-
review-

优先级	类别	影响程度	前缀	规则数量
1	语气与语调	CRITICAL	`voice-`	4
2	结构与组织	CRITICAL	`structure-`	10
3	清晰度与语言表达	HIGH	`clarity-`	6
4	代码示例	HIGH	`code-`	7
5	格式与语法	MEDIUM-HIGH	`format-`	8
6	导航与链接	MEDIUM-HIGH	`nav-`	6
7	易扫描性与可读性	MEDIUM	`scan-`	2
8	内容整洁度	MEDIUM	`hygiene-`	6
9	审核与测试	LOW-MEDIUM	`review-`	3

Quick Reference

快速参考

Read only what is needed for the current scope:

Category map and impact rationale:
```
rules/_sections.md
```
Rule-level guidance and examples:
```
rules/<prefix>-*.md
```

Example rule files:

rules/voice-defaults.md
rules/structure-diataxis.md
rules/clarity-defaults.md

Each rule file contains:

Why the rule matters
Incorrect example
Correct example

仅阅读当前场景所需内容：

类别映射及影响说明：
```
rules/_sections.md
```
规则级指导与示例：
```
rules/<prefix>-*.md
```

示例规则文件：

rules/voice-defaults.md
rules/structure-diataxis.md
rules/clarity-defaults.md

每个规则文件包含：

规则的重要性说明
错误示例
正确示例

Review Output Contract

审核输出规范

Report findings in this format:

markdown

undefined

请按以下格式提交审核结果：

markdown

undefined

Documentation Audit Findings

path/to/file.md

[CRITICAL]
```
voice-defaults
```
: Passive voice obscures who performs the action.
- Fix: Rewrite "The configuration is loaded by the server" as "The server loads the configuration."

[CRITICAL]
```
voice-defaults
```
: Passive voice obscures who performs the action.
- Fix: Rewrite "The configuration is loaded by the server" as "The server loads the configuration."

path/to/clean-file.md

✓ pass


- Group findings by file.
- Use `file:line` when line numbers are available.
- State issue and propose a concrete fix.
- Include clean files as `✓ pass`.

✓ pass


- 按文件分组展示问题。
- 若有行号，使用`file:line`格式标注。
- 说明问题并提出明确的修复方案。
- 将无问题的文件标记为`✓ pass`。

docs-writing

Original

Translation

Documentation Writing

技术文档编写

Doc Writing/Audit Workflow

文档编写/审核工作流

Rule Categories by Priority

按优先级划分的规则类别

Quick Reference

快速参考

Review Output Contract

审核输出规范

Documentation Audit Findings

Documentation Audit Findings

path/to/file.md

path/to/file.md

path/to/clean-file.md

path/to/clean-file.md