doc-quality-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation Quality Review

文档质量评审

Assess whether documentation is well-written, consistent, and appropriate for its audience. The output is a scored review with specific findings — not rewrites.

评估文档是否撰写精良、风格一致且符合目标受众需求。输出内容为带有具体问题点的评分式评审报告，而非重写后的文档。

When to Use

使用场景

Before releases — ensure docs meet a quality bar
During doc review — structured alternative to "looks good to me"
When users report docs are confusing, inconsistent, or too technical
After bulk doc generation — verify machine-written docs read naturally
Periodic quality check on documentation health

发布前——确保文档达到质量标准
文档评审期间——替代"看起来没问题"的结构化评审方式
用户反馈文档存在混淆、不一致或过于技术化时
批量生成文档后——验证机器生成的文档读起来是否自然
定期检查文档整体健康状况

Quick Reference

快速参考

Resource	Purpose	Load when
`references/quality-dimensions.md`	Scoring rubrics for each dimension	Always (Phase 1)
`references/style-checklist.md`	Concrete style rules for common issues	Phase 2 (review pass)

资源	用途	加载时机
`references/quality-dimensions.md`	各维度的评分细则	始终加载（第一阶段）
`references/style-checklist.md`	针对常见问题的具体风格规则	第二阶段（评审环节）

Workflow Overview

工作流程概述

Phase 1: Scope       → Identify docs to review and their intended audience
Phase 2: Review      → Score each doc across quality dimensions
Phase 3: Synthesize  → Aggregate findings, identify patterns
Phase 4: Report      → Produce the scored quality review

Phase 1: Scope       → 确定待评审文档及其目标受众
Phase 2: Review      → 针对各质量维度为每份文档评分
Phase 3: Synthesize  → 汇总问题点，识别共性模式
Phase 4: Report      → 生成评分式质量评审报告

Phase 1: Scope the Review

第一阶段：确定评审范围

Before reviewing, establish context:

Identify the docs — which files or sections are in scope?
Identify the audience — who reads these docs? (new user, experienced developer, operator, contributor)
Identify the doc type — reference, tutorial, guide, explanation, or README?
Load the rubrics — read
```
references/quality-dimensions.md
```
to calibrate scoring

The audience and doc type determine which dimensions matter most. A reference page has different quality criteria than a tutorial.

开始评审前，先明确上下文：

确定文档范围——哪些文件或章节需要评审？
确定目标受众——谁会阅读这些文档？（新用户、资深开发者、运维人员、贡献者）
确定文档类型——参考文档、教程、指南、说明文档还是README？
加载评分细则——阅读
```
references/quality-dimensions.md
```
以校准评分标准

受众和文档类型决定了哪些维度最为重要。参考文档的质量标准与教程截然不同。

Phase 2: Review Each Document

第二阶段：评审每份文档

Score each document across five dimensions. Read the full document before scoring.

从五个维度为每份文档评分，评分前需通读完整文档。

Dimension 1: Readability

维度1：可读性

How easily can the target audience read and understand this?

Score	Criteria
5	Clear, concise prose. Short paragraphs. Active voice. Appropriate vocabulary for audience
4	Generally clear. Minor instances of passive voice, long sentences, or unnecessary jargon
3	Readable but effortful. Multiple long paragraphs, some jargon without definition, occasional ambiguity
2	Difficult. Dense prose, heavy jargon, passive constructions, unclear antecedents
1	Impenetrable. Wall of text, undefined terms, ambiguous instructions, no structure

What to check:

Sentence length — flag sentences over 30 words
Paragraph length — flag paragraphs over 6 sentences
Passive voice density — flag sections where >40% of sentences are passive
Jargon — flag technical terms used without definition on first occurrence
Ambiguous pronouns — "it", "this", "that" without clear referent
Nominalizations — "perform an installation" instead of "install"

目标受众能否轻松阅读并理解内容？

分数	评判标准
5	文本清晰简洁，段落简短，使用主动语态，词汇符合受众水平
4	整体清晰，仅存在少量被动语态、长句或不必要的行话
3	可读但需费力，存在多个长段落、部分无定义的行话，偶尔出现歧义
2	难以理解，文本晦涩、行话密集、被动结构多，指代模糊
1	完全无法理解，大段无结构文本、术语无定义、指令模糊

检查要点：

句子长度——标记超过30个单词的句子
段落长度——标记超过6句的段落
被动语态占比——标记被动语态占比超过40%的章节
行话——标记首次出现未定义的技术术语
模糊代词——标记无明确指代的"it"、"this"、"that"
名词化表达——标记如"perform an installation"而非"install"的冗余表达

Dimension 2: Consistency

维度2：一致性

Does this doc use the same terms, formatting, and conventions throughout — and match the rest of the doc set?

Score	Criteria
5	Consistent terminology, formatting, heading style, code block conventions, and tone throughout
4	Minor inconsistencies (e.g., "config" vs "configuration" in different sections)
3	Noticeable inconsistencies across sections but each section is internally consistent
2	Frequent inconsistencies in terminology, formatting, or conventions
1	No discernible consistency — reads like it was written by different people at different times

What to check:

Term alignment — same concept should use the same word everywhere
Heading hierarchy — consistent use of
```
##
```
vs
```
###
```
, capitalization style
Code block formatting — language tags present, consistent indentation
List formatting — bullet vs number, punctuation, capitalization
Admonition/callout style — consistent use of note/warning/tip conventions
Tense — consistent within a doc type (imperative for instructions, present for descriptions)

文档内部及整个文档集是否使用统一的术语、格式和规范？

分数	评判标准
5	术语、格式、标题风格、代码块规范和语气完全一致
4	存在轻微不一致（如不同章节中"config"与"configuration"混用）
3	章节间存在明显不一致，但各章节内部保持一致
2	术语、格式或规范频繁不一致
1	完全无一致性，看起来像是不同人在不同时间撰写的

检查要点：

术语统一——同一概念应全程使用相同词汇
标题层级——
```
##
```
与
```
###
```
的使用、大小写风格保持一致
代码块格式——包含语言标签，缩进一致
列表格式——项目符号/编号、标点、大小写保持一致
提示框风格——note/warning/tip等提示框的使用规范保持一致
时态——同一文档类型内时态统一（说明文档用祈使句，描述性文档用一般现在时）

Dimension 3: Audience Fit

维度3：受众适配度

Is the content calibrated to the right level for its intended readers?

Score	Criteria
5	Perfectly pitched. Prerequisites stated. Appropriate depth. No unexplained leaps
4	Mostly well-calibrated. Occasional assumption of knowledge not established
3	Uneven. Some sections too basic, others too advanced. Prerequisites unclear
2	Significant mismatch. Beginner docs assume expert knowledge, or expert docs over-explain basics
1	Wrong audience entirely. Content pitched at a different reader than intended

What to check:

Prerequisite assumptions — what must the reader already know?
Explanation depth — does it match the audience's expected background?
Context gaps — would a new reader understand why, not just what?
Leaps — does the doc jump from basic to advanced without transition?
Condescension — does it over-explain things the audience already knows?

内容难度是否与目标读者的水平匹配？

分数	评判标准
5	完美适配，明确列出前置要求，深度恰当，无突兀的逻辑跳跃
4	整体适配良好，偶尔假设读者具备未明确说明的知识
3	适配度不均，部分内容过于基础，部分过于深入，前置要求模糊
2	严重不匹配，面向新手的文档假设读者具备专家知识，或面向专家的文档过度解释基础内容
1	完全不符合受众定位，内容面向与预期完全不同的读者

检查要点：

前置知识假设——读者需要预先掌握哪些内容？
解释深度——是否符合受众的预期背景？
上下文缺失——新读者是否能理解"为什么"而非仅"是什么"？
逻辑跳跃——文档是否从基础直接跳到高级内容而无过渡？
过度解释——是否对受众已掌握的内容赘述过多？

Dimension 4: Structure & Scannability

维度4：结构与可扫描性

Can a reader find what they need without reading linearly?

Score	Criteria
5	Logical heading hierarchy. Scannable sections. Tables for reference data. Clear entry points
4	Good structure. Minor issues with heading granularity or section ordering
3	Adequate structure but some sections are too long or headers don't reflect content
2	Poor structure. Key information buried in prose. Headings misleading or inconsistent
1	No useful structure. Single long section with no headings, or headings that don't help navigation

What to check:

Heading hierarchy — does it create a useful outline?
Front-loading — are key facts early in each section, or buried at the end?
Tables vs prose — is reference data in tables or hidden in paragraphs?
Section length — flag sections over 500 words without a subheading
TL;DR — do long docs have a summary or overview section?

读者无需逐行阅读就能找到所需内容吗？

分数	评判标准
5	标题层级逻辑清晰，章节易于扫描，参考数据使用表格呈现，有明确的入口
4	结构良好，仅存在标题粒度或章节排序的轻微问题
3	结构尚可，但部分章节过长或标题与内容不符
2	结构糟糕，关键信息隐藏在文本中，标题误导性强或不一致
1	无有效结构，仅为无标题的长段落，或标题对导航无帮助

检查要点：

标题层级——是否形成有用的大纲？
重点前置——关键信息是否在章节开头，而非末尾？
表格与文本——参考数据是否用表格呈现，而非隐藏在段落中？
章节长度——标记超过500字且无副标题的章节
TL;DR——长篇文档是否有摘要或概述部分？

Dimension 5: Actionability

维度5：可操作性

Can the reader do something after reading? (Weighted differently by doc type.)

Score	Criteria
5	Clear next steps. Commands are copy-pasteable. Examples are complete and runnable
4	Mostly actionable. Minor gaps in examples or steps
3	Partially actionable. Some instructions unclear or missing context
2	Weakly actionable. Reader knows about the topic but not how to apply it
1	Not actionable. Pure description with no path to action

What to check:

Code examples — do they work if copy-pasted? Are imports included?
Commands — are they complete with required flags and paths?
Steps — are they sequential and numbered? Any missing steps?
Expected output — does the doc show what success looks like?
Error guidance — if something goes wrong, does the doc say what to do?

读者阅读后能否采取实际行动？（权重因文档类型而异）

分数	评判标准
5	下一步操作清晰，命令可直接复制粘贴，示例完整可运行
4	整体可操作，示例或步骤存在轻微缺失
3	部分可操作，部分指令模糊或缺少上下文
2	可操作性弱，读者仅了解主题但不知如何应用
1	完全不可操作，仅为描述性内容，无行动路径

检查要点：

代码示例——复制粘贴后能否运行？是否包含必要的导入语句？
命令——是否包含所需的参数和路径？
步骤——是否按顺序编号？有无缺失步骤？
预期输出——文档是否展示成功状态的样子？
错误指引——出现问题时，文档是否说明解决方法？

Dimension Weighting by Doc Type

按文档类型划分的维度权重

Dimension	Reference	Tutorial	Guide	Explanation	README
Readability	1.0	1.2	1.2	1.3	1.2
Consistency	1.2	0.8	1.0	0.8	1.0
Audience Fit	0.8	1.3	1.2	1.2	1.3
Structure	1.3	1.0	1.0	0.8	1.0
Actionability	1.0	1.5	1.3	0.5	1.0

维度	参考文档	教程	指南	说明文档	README
可读性	1.0	1.2	1.2	1.3	1.2
一致性	1.2	0.8	1.0	0.8	1.0
受众适配度	0.8	1.3	1.2	1.2	1.3
结构	1.3	1.0	1.0	0.8	1.0
可操作性	1.0	1.5	1.3	0.5	1.0

Phase 3: Synthesize Findings

第三阶段：汇总问题点

After scoring individual docs, look for patterns:

Systemic issues — same problem across many docs (e.g., inconsistent terminology everywhere)
Outliers — one doc much better or worse than the rest
Audience mismatches — docs in the wrong section for their actual audience
Style drift — sections written at different times with different conventions

Systemic issues are more valuable to fix than individual ones — fixing the pattern fixes many docs at once.

完成单份文档评分后，寻找共性模式：

系统性问题——多个文档存在相同问题（如全文档集术语不一致）
异常文档——某份文档质量远高于或低于其他文档
受众错位——文档放置的位置与实际受众不符
风格漂移——不同时间撰写的章节风格差异明显

系统性问题比单个问题更值得修复——解决模式问题可一次性修复多个文档。

Phase 4: Produce the Quality Review

第四阶段：生成质量评审报告

Report Format

报告格式

markdown

undefined

markdown

undefined

Documentation Quality Review

文档质量评审

Review date: YYYY-MM-DD Scope: [files or sections reviewed] Target audience: [who these docs serve] Doc type: [reference / tutorial / guide / explanation / mixed]

评审日期: YYYY-MM-DD 评审范围: [待评审文件或章节] 目标受众: [文档服务对象] 文档类型: [参考文档 / 教程 / 指南 / 说明文档 / 混合类型]

Summary

摘要

[2-3 sentences: overall quality assessment]

Overall scores (weighted):

Dimension	Raw Score	Weight	Weighted
Readability	N/5	Nx	N
Consistency	N/5	Nx	N
Audience Fit	N/5	Nx	N
Structure	N/5	Nx	N
Actionability	N/5	Nx	N
Total			N / 25

Quality grade: [A (22-25) / B (18-21) / C (14-17) / D (10-13) / F (<10)]

[2-3句话：整体质量评估]

加权总分：

维度	原始分数	权重	加权分数
可读性	N/5	Nx	N
一致性	N/5	Nx	N
受众适配度	N/5	Nx	N
结构	N/5	Nx	N
可操作性	N/5	Nx	N
总分			N / 25

质量等级: [A (22-25) / B (18-21) / C (14-17) / D (10-13) / F (<10)]

Findings

问题点

Critical (must fix before publish)

严重问题（发布前必须修复）

#	File	Dimension	Issue	Fix
1	[path:line]	[dimension]	[specific problem]	[specific fix]

#	文件	维度	问题	修复方案
1	[路径:行号]	[维度]	[具体问题]	[具体修复方案]

Major (should fix)

主要问题（建议修复）

#	File	Dimension	Issue	Fix

#	文件	维度	问题	修复方案

Minor (nice to fix)

次要问题（可选修复）

#	File	Dimension	Issue	Suggestion

#	文件	维度	问题	建议方案

Systemic Issues

系统性问题

[Issue pattern name]

[问题模式名称]

Affected docs: [list] Dimension: [which] Pattern: [what's happening across docs] Recommended fix: [one-time fix that addresses all instances]

受影响文档: [列表] 涉及维度: [对应维度] 模式描述: [多份文档存在的共性问题] 推荐修复方案: [一次性解决所有实例的方案]

Per-Document Scores

单文档评分

Document	Read.	Cons.	Aud.	Struct.	Action.	Weighted Total
[path]	N	N	N	N	N	N

文档	可读性	一致性	受众适配	结构	可操作性	加权总分
[路径]	N	N	N	N	N	N

Strengths

优势

[What's working well — cite specific examples worth emulating]

---

[表现良好的方面——列举值得借鉴的具体示例]

---

Integration with Other Doc Skills

与其他文档技能的集成

doc-maintenance         →  Structural health (links, orphans, folders)
doc-claim-validator     →  Semantic accuracy (do claims match code?)
doc-completeness-audit  →  Topic coverage (is everything documented?)
doc-quality-review      →  Prose quality (is it well-written?)
doc-architecture-review →  Information architecture (is it findable?)

doc-maintenance         → 结构健康度（链接、孤立文档、文件夹）
doc-claim-validator     → 语义准确性（表述与代码是否一致？）
doc-completeness-audit  → 主题覆盖度（所有内容是否都已文档化？）
doc-quality-review      → 文本质量（撰写是否精良？）
doc-architecture-review → 信息架构（内容是否易于查找？）

Anti-Patterns

反模式

Do not rewrite docs during the review — produce findings, not rewrites
Do not score without reading the full document — skimming misses context
Do not apply tutorial standards to reference docs or vice versa — use the weighting table
Do not penalize technical precision as "jargon" in docs for technical audiences
Do not flag style preferences as quality issues — "I'd phrase it differently" is not a finding
Do not review generated API docs (JSDoc, Sphinx auto) — review the source comments instead
Do not score docs in
```
docs/archive/
```
— they are historical

评审期间不要重写文档——只输出问题点，而非重写内容
不要未通读完整文档就评分——略读会遗漏上下文
不要将教程标准套用到参考文档，反之亦然——使用权重表
不要在面向技术受众的文档中，将技术准确性视为"行话"而扣分
不要将个人风格偏好视为质量问题——"我会换种方式表述"不属于问题点
不要评审自动生成的API文档（JSDoc、Sphinx自动生成）——应评审源注释
不要对
```
docs/archive/
```
下的文档评分——这些是历史文档

Bundled Resources

附带资源

References

参考文件

```
references/quality-dimensions.md
```
— Detailed scoring rubrics with examples for each score level
```
references/style-checklist.md
```
— Concrete style rules for the most common quality issues

```
references/quality-dimensions.md
```
— 包含各分数等级示例的详细评分细则
```
references/style-checklist.md
```
— 针对最常见质量问题的具体风格规则