Back to Details

reviewing-technical-prose

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Reviewing technical prose

技术文稿评审

REQUIRED BACKGROUND: the 
technical-writing
skill, including 
references/style.md
(banned constructions) and 
references/truth.md
(claim rules).
必备背景知识： 
technical-writing
skill，包括
references/style.md
（禁用结构）和
references/truth.md
（声明规则）。

Overview

概述

Editing is diagnosis, not a rewrite quota. Every edit names the concrete defect it fixes; the smallest edit that fixes it wins. Rewriting natural or approved language without a named defect is itself a defect.
Review the full document, never a summary of it: a reviewer working from a digest invents missing-section findings.
编辑是诊断问题，而非完成改写指标。每一处修改都需明确指出其修复的具体问题；能解决问题的最小修改即为最优方案。若无明确问题就改写自然或已获认可的表述，本身就是一种问题。
需评审完整文档，而非文档摘要：基于摘要开展评审的人员会凭空提出“缺失章节”类问题。

When to invoke, and not

适用与不适用场景

Invoke when reviewing or rewriting someone else's technical text, when producing a findings report on a document, and as the final pass before delivering anything you wrote yourself. Do NOT invoke for code review (only the prose in it), and do not use a review pass to relitigate settled decisions, expand scope, or restyle a document onto your own preferences.
适用场景：评审或改写他人技术文本、撰写文档问题报告，以及交付自行撰写的内容前的最终检查环节。不适用场景：代码评审（仅针对其中的文稿部分除外），且不得利用评审环节重新讨论已敲定的决策、扩大范围，或是按照个人偏好重新调整文档风格。

Severity mapping

严重程度映射规则

  • BLOCKER: hard-rule violations (banned dashes, changelog sections, delivery history in prose) and any claim the cited source does not support or that traces to nothing.
  • WARNING: banned constructions, structural defects (question headings, buried conclusions, rearrangeable paragraphs), and claims supported only loosely.
  • OBS: ambiguity, missing polish, and anything an attentive author would likely catch.
  • BLOCKER（阻塞级）：违反硬性规则（如禁用破折号、变更日志章节、文稿中包含交付历史），以及任何无引用来源支持或无依据的声明。
  • WARNING（警告级）：使用禁用结构、存在结构性问题（如疑问式标题、结论后置、段落顺序可随意调整），以及仅得到松散支持的声明。
  • OBS（观察级）：表述模糊、缺乏润色，以及细心的作者可能自行发现的问题。

Rewriting someone else's text

改写他人文本

One requirement above all rules: the content stays identical. Work in this order:
  1. Read the source and mark every banned construction and word-choice violation.
  2. Write a version and read it aloud.
  3. Ask three control questions: which sentence still sounds like a language model; did the rewrite add or drop a fact, number, date, name, source, or claim; and does the rewrite recreate a removed pattern in a new rhetorical form? Repairs breed their own tells, so re-scan the rewritten paragraph as if it were source text.
  4. Repair what the control questions surface. An addition and a loss both count as errors, even when the text reads better for it.
Never add a fact to finish a sentence: ask the author or pick a simpler sentence. If a sentence stays wooden after two attempts, rewrite the whole paragraph around its main point. Change only running prose: code blocks, frontmatter, table data, and link targets stay as they are.
Two more rules frame every rewrite. The rewrite keeps the document's language: a Dutch document comes back in Dutch, with the structural and truth rules applied as always and the English-specific vocabulary checks replaced by that language's own list where one exists. And when the author is reachable, the diff is the proposal: show the rewrite before overwriting their text; unattended in a repository, the commit is the proposal and review does the same job.
When the source text asserts nothing recoverable (setups, glosses, meaning-sentences), the correct rewrite is deletion plus a marked gap (
**[input wanted: ...]**
) where a real claim should stand. A rewrite full of marked gaps is the intended outcome for claim-free source text, not a failure.
所有规则之上的核心要求：内容必须保持一致。请按以下步骤操作：
  1. 阅读原文，标记所有禁用结构和用词违规之处。
  2. 撰写改写版本并大声朗读。
  3. 提出三个验证问题：哪句话仍带有语言模型的痕迹？改写过程中是否添加或遗漏了事实、数字、日期、名称、来源或声明？改写是否以新的修辞形式重现了已移除的模式？修改往往会产生新的问题，因此需将改写后的段落当作原文重新扫描检查。
  4. 修复验证问题发现的问题。即便改写后的文本读起来更流畅，添加或遗漏内容都属于错误。
切勿为了凑完整句子而添加事实：可询问作者或改用更简洁的句子。若经过两次尝试后句子仍生硬，可围绕核心观点重写整个段落。仅修改正文内容：代码块、前置信息、表格数据和链接目标需保持原样。
改写还需遵循另外两条规则。改写需保留文档的语言：荷兰语文档改写后仍为荷兰语，始终遵循结构和真实性规则，若该语言有专属词汇检查清单，则替换英文特定词汇检查项。若作者可联系，差异内容即为修改建议：在覆盖作者文本前先展示改写版本；若文档在仓库中无人维护，则提交的变更即为修改建议，评审环节承担相同职责。
若原文无任何可保留的有效声明（如铺垫、注释、无意义句子），正确的处理方式是删除内容并在应放置有效声明的位置标记空白（
**[input wanted: ...]**
）。对于无有效声明的原文，改写后满是标记空白是预期结果，而非失败。

What you do not flag

无需标记的内容

The banned-constructions list helps recognize machine text; it proves nothing by itself, and every pattern also occurs in good human writing. Flag only when several signs coincide in the same paragraph.
  • Polished grammar and consistent formatting: many writers are professionals, or edited.
  • One repeated sentence opening: repetition can be rhythm. Fix only when it adds nothing.
  • One short sentence for emphasis: only a row of fragments is a problem.
  • Formal words in general: the list names specific words; not every formal word needs simplifying.
  • A factual contrast: "the pipeline sets the tag, the developer does not" is a statement, not antithesis.
  • A serious alternative the reader would genuinely weigh: it belongs in the document.
  • Qualifiers that bound something: scope, assumptions, and safety or legal notes stay. Only the stacking goes.
  • A reference to the previous situation in a migration doc or release note: there the change IS the subject.
  • A quoted word: never rewrite inside a citation, a title, or an example that discusses the word.
  • Metaphor that explains: only the decoration around it goes.
  • Deliberate awkwardness: a clear fragment or lopsided sentence is not a defect merely because it could be polished.
禁用结构清单有助于识别机器生成文本，但仅凭单一模式无法判定，因为所有这些模式也可能出现在优质人工撰写的文本中。仅当同一段落中出现多个相关迹象时才标记问题。
  • 语法规范、格式一致：许多作者是专业人士或已接受过编辑。
  • 重复的句子开头：重复可能是为了营造节奏。仅当重复无任何作用时才修改。
  • 用于强调的短句：只有连续的碎片句才是问题。
  • 正式词汇：清单中仅列出特定词汇；并非所有正式词汇都需要简化。
  • 事实对比：“流水线设置标签，开发者不设置”是陈述事实，而非对偶修辞。
  • 读者需认真考量的合理替代方案：这类内容属于文档必要部分。
  • 限定范围的修饰语：范围说明、假设前提、安全或法律提示需保留。仅需移除堆叠的修饰语。
  • 迁移文档或发布说明中提及之前的情况：这类文档的主题就是变更。
  • 引用的词汇：切勿改写引用内容、标题或讨论该词汇的示例。
  • 用于解释的隐喻：仅需移除隐喻周围的修饰性内容。
  • 刻意为之的生硬表述：清晰的碎片句或不对称句子仅因可润色就被视为问题。

Review reports

评审报告

  • Verdict in the first line, findings ordered most severe first.
  • Severity vocabulary defined in the report that uses it: BLOCKER (cannot proceed), WARNING (likely rework; fix but not blocking), OBS (worth noting).
  • Every finding: one sentence stating the defect, a location (
    file:line
    , section, task ID), a proposed fix, and a confidence level.
  • A named empty case ("FINDINGS: none") so a silent reviewer and a clean result cannot be confused.
  • A document claim contradicted by the code is a defect in the document; report it with the conflicting source. An unrelated bug you noticed in passing is not your finding: stay in scope, do not restyle, do not relitigate settled decisions.
  • Re-reviews list only what remains; resolved findings are not re-listed.
  • Acknowledge what is good; a review that only objects is not calibrated.
  • 评审结论置于首行，问题按严重程度从高到低排序。
  • 报告中需定义严重程度术语：BLOCKER（阻塞级）（无法继续推进）、WARNING（警告级）（可能需要返工；需修复但不阻塞流程）、OBS（观察级）（值得注意）。
  • 每个问题需包含：一句说明问题的表述、位置（
    文件:行号
    、章节、任务ID）、建议修复方案，以及置信度。
  • 需明确标记无问题情况（“问题：无”），避免将未反馈的评审与无问题结果混淆。
  • 文档声明与代码矛盾属于文档问题：需附上冲突来源进行报告。偶然发现的无关Bug不属于评审范围：需聚焦本职工作，不得重新调整风格，不得重新讨论已敲定的决策。
  • 复审仅列出剩余问题；已解决的问题无需重复列出。
  • 需认可文档的优点；仅提出反对意见的评审是不客观的。

Delivery checklist

交付检查清单

Before any document goes out:
  • Matched to the existing documents in the same directory, and added to the 
    README.md
    index if one exists
  • No em dashes, en dashes, or 
    --
    ; no changelog section or "last updated" field; no ticket keys, phases, or SHAs in prose
  • No banned constructions (references/style.md); check at least the summary and the closing paragraphs
  • Headings name the content: no question forms, no "What X means", no heading repeated in its first sentence
  • Conclusion first at document, chapter, and paragraph level
  • Procedures: one action per sentence, with an actor
  • Every non-trivial choice has its reasoning and a serious alternative recorded
  • The costs are in, not only the benefits
  • Fact and proposal are distinguishable; estimates labeled; unknowns explicitly unknown
  • Every claim with a number traces to a source named in the document
  • References checked by following them: chapter numbers, relative links, and file names actually exist (they break silently on every restructure)
  • Terms consistent and defined at first use; one term per concept
  • Read aloud: at least the summary; no row of fragments, no three sentences with the same opening
  • Remove-the-name test on the opening and summary: with the product name deleted, a stranger can still tell what the text is about
  • On a rewrite: no fact, number, date, or source added or lost
任何文档交付前需完成以下检查：
  • 一致性检查：与同一目录下的现有文档格式匹配，若存在
    README.md
    索引则将其加入其中
  • 符号检查：无长破折号、短破折号或
    --
    ；无变更日志章节或“最后更新”字段；文稿中无工单编号、阶段标识或SHA值
  • 禁用结构检查：无
    references/style.md
    中列出的禁用结构；至少检查摘要和结尾段落
  • 标题检查：标题需明确内容；无疑问式标题、“X的含义”类标题，且标题不得在段落首句重复出现
  • 结论前置：文档、章节和段落均需先给出结论
  • 流程检查：每个句子对应一个操作，且明确执行主体
  • 决策记录：所有非琐碎的决策需记录其理由和合理替代方案
  • 成本说明：需包含成本信息，而非仅提及收益
  • 事实与提案区分：估算内容需标注；未知信息需明确说明
  • 数据溯源：所有带数字的声明均需追溯至文档中提及的来源
  • 引用验证：点击检查所有引用；章节编号、相对链接和文件名均真实存在（结构调整时这些内容会无声失效）
  • 术语一致性：术语定义需一致且首次出现时定义；一个概念对应一个术语
  • 朗读检查：至少朗读摘要；无连续碎片句，无三个开头相同的句子
  • 去名称测试：删除产品名称后，陌生人仍能理解文本内容
  • 改写验证：未添加或遗漏任何事实、数字、日期或来源