awesome-document-style

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Document Style

文档风格规范

Principle

原则

Edit for clarity, specificity, continuity, and factual honesty.

Do not try to trick AI detectors. Do not add fake imperfections, fake anecdotes, slang, typos, or unsupported personal details. Preserve the author's meaning. If a claim is unsupported, narrow it, mark it as needing a source, or remove it.

编辑以清晰性、具体性、连贯性和事实准确性为目标。

不得试图欺骗AI检测工具。不得添加虚假的不完美内容、虚构轶事、俚语、拼写错误或无依据的个人细节。保留作者的原意。如果某个论断没有依据，缩小其表述范围、标记为需要来源，或者直接删除。

Input rules

输入规则

Work only on the Markdown document or file paths the user provides.
Preserve YAML frontmatter, code blocks, commands, tables with real data, footnotes, links, and citations unless they are clearly broken.
Do not invent sources, numbers, dates, author names, product features, benchmark results, quotes, or case studies.
If a citation marker looks like an internal chatbot artifact, remove the artifact and keep or repair the underlying real citation only if it exists.
If the document contains placeholders, either fill them from context or mark them as TODO. Do not leave publishing placeholders in final prose.

仅处理用户提供的Markdown文档或文件路径。
保留YAML frontmatter、代码块、命令、包含真实数据的表格、脚注、链接和引用，除非它们明显损坏。
不得编造来源、数字、日期、作者姓名、产品功能、基准测试结果、引述或案例研究。
如果引用标记看起来是聊天机器人的内部痕迹，仅当存在真实的底层引用时，才移除痕迹并保留或修复真实引用。
如果文档包含占位符，要么根据上下文填充，要么标记为TODO。不得在最终文案中保留出版用占位符。

Pass 1: Mechanical artifact cleanup

第1步：机械痕迹清理

Search for and remove or flag these classes of artifacts:

Unresolved chatbot citation and tool markers:

:contentReference[oaicite:N]

oai_citation:N

turn0search0

and its

turn\d+(search|fetch|file|image)\d+

siblings,

[cite_start]

[cite: N]

[attached_file:N]

grok_card://

vertexaisearch

grounding-redirect links.

AI-tool URL parameters:

```
utm_source=chatgpt.com
```
```
utm_source=openai
```
```
utm_source=claude.ai
```
```
utm_source=perplexity.ai
```
```
utm_source=copilot.com
```

Visible placeholders:
- ```
[Your Name]
```
- ```
[INSERT SOURCE]
```
- ```
[Describe section]
```
- ```
2025-XX-XX
```
- HTML comments that say add, insert, fill, replace, or TODO
Zero-width or invisible formatting characters.
Chat UI leftovers:
- “Certainly”
- “Great question”
- “I hope this helps”
- “As an AI language model”
- “Would you like me to”
- “Here’s a polished version”

The markers above are enough to run this pass standalone. If the

awesome-humanize-en

skill is installed alongside this one, its

references/chatbot-artifacts.md

carries the full catalog — every marker with its regex, its source, and its false-positive boundary — and is worth opening for an unfamiliar marker or an ambiguous match.

查找并移除或标记以下几类痕迹：

未解析的聊天机器人引用和工具标记：

:contentReference[oaicite:N]

、

oai_citation:N

、

turn0search0

及其同类格式

turn\\d+(search|fetch|file|image)\\d+

、

[cite_start]

、

[cite: N]

、

[attached_file:N]

、

grok_card://

、

vertexaisearch

基础重定向链接。

AI工具URL参数：

```
utm_source=chatgpt.com
```
```
utm_source=openai
```
```
utm_source=claude.ai
```
```
utm_source=perplexity.ai
```
```
utm_source=copilot.com
```

可见占位符：
- ```
[Your Name]
```
- ```
[INSERT SOURCE]
```
- ```
[Describe section]
```
- ```
2025-XX-XX
```
- 包含add、insert、fill、replace或TODO字样的HTML注释
零宽或不可见格式字符。
聊天界面残留语：
- “Certainly”
- “Great question”
- “I hope this helps”
- “As an AI language model”
- “Would you like me to”
- “Here’s a polished version”

以上标记足以独立完成本步骤的清理工作。如果同时安装了

awesome-humanize-en

技能，其

references/chatbot-artifacts.md

文件包含完整的目录——每个标记都配有对应的正则表达式、来源和误判边界——遇到不熟悉的标记或模糊匹配时值得查阅。

Pass 2: Markdown structure cleanup

第2步：Markdown结构清理

Keep Markdown simple and readable in plain text.
Do not hard-wrap prose to a fixed column width. Keep each paragraph on a single continuous line of any length and let the editor soft-wrap — lines are not capped at 80, 100, or any other limit. Do not insert manual line breaks inside a paragraph, list item, or heading. If the document is already hard-wrapped at a fixed column (a common AI default of ~100 characters, which splits one sentence across several physical lines, breaks reading flow, and creates noisy diffs), reflow it: join the split lines back into one line per paragraph. Insert a line break only where Markdown needs one: between paragraphs, between list items, and around headings, code blocks, and tables.
Use one
```
#
```
title only if the document needs it.
Do not skip heading levels.
Replace vague headings with specific headings.
- Bad:
```
## Overview
```
- Better:
```
## How the retry queue handles failed payments
```
- Renaming a heading breaks its anchor links: check for inbound
```
#anchor
```
  links and a TOC first; when they exist, flag the rename as a suggestion instead of applying it.
Remove decorative horizontal rules unless they separate distinct document sections.
Prefer straight quotes (
```
'
```
```
"
```
) and a hyphen or comma-set clause over a gratuitous em-dash (
```
—
```
) in the prose you write or rewrite — flawless hand-set typography reads as machine output in plain text. The same goes for the arrow glyph (
```
→
```
,
```
⇒
```
) used as a prose connective (
```
input → output
```
,
```
problem → solution
```
,
```
renamed → new name
```
): write the relation in words (
```
becomes
```
,
```
then
```
,
```
leads to
```
,
```
renamed to
```
) or, in technical text where a symbol reads better, use ASCII
```
->
```
. Do not touch: quotes, dashes, or arrows inside code, commands, or fenced blocks; an arrow that is real notation (a diagram, a state machine, a math or chemistry expression, quoted tool output, a keyboard shortcut path like
```
File → Save
```
naming actual UI); a deliberate typographic document (a published/formatted article) where the style is consistent and intentional; or a glyph inside a quotation or proper name. Never convert to guillemets or any national style. This is about the characters, not meaning — do not change wording to remove a dash or an arrow.
Write a number a reader could count or verify as digits, not words —
```
9 supported sites
```
,
```
4 permissions
```
,
```
2 clicks
```
,
```
12 months
```
— including 0–9 and at the start of a sentence. A group of digits has a different shape from a group of letters, so it survives the scan that skips the words around it (NN/g eyetracking); spelled out, the same fact dissolves into the sentence. Headings, table cells, and any one-line summary take digits first — those are the lines a reader lands on.
- Keep words where the number is not data:
```
one
```
  as a pronoun or inside a fixed term (“one person, one vote”, “which one”, “one-time code”, “one-click”), a bare pronoun pair (“the two agree”, “all three”), vague scale used as rhetoric (“thousands of throwaway profiles”, “by the hundred”), and magnitudes whose zeros stop being readable (“24 billion”, not
```
24,000,000,000
```
  ).
- Never mix the two forms in one sentence: “600 emoji, not six defaults” is the bug. When a rhetorical
```
one
```
  sits next to the count, recast the sentence or leave both as words rather than digit-plus-word.
- Keep one thousands separator per document (
```
50,000
```
  , not
```
50 000
```
  in one paragraph and
```
40,000
```
  in the next), and hyphenate compound modifiers:
```
2-day-old post
```
  ,
```
6-digit code
```
  .
- The print style guides say the opposite for 1–9 (AP spells out one–nine, Chicago one–one hundred) because they are print rules. If the document declares a house style, or the author ran
```
awesome-grammar-check
```
  with a
```
style-guide
```
  argument, that declaration wins over this bullet — say which rule you applied.
Remove excessive bold. Use bold for UI labels or essential emphasis only.
Convert tiny tables into prose unless the table contains comparable data.
Use ordered lists only for sequences. Use unordered lists only for genuinely parallel items.
Collapse “Key Takeaways”, “In Summary”, and “Conclusion” sections unless they contain new information.

保持Markdown在纯文本下的简洁性和可读性。
不要给文案设置固定列宽的硬换行。让每个段落保持为任意长度的连续单行，由编辑器负责软换行——行长度不受80、100或任何其他限制。不得在段落、列表项或标题内部插入手动换行符。如果文档已经采用固定列宽的硬换行（AI生成内容的常见默认值约为100字符，会将一个句子拆分到多个物理行，打断阅读流畅度，还会产生大量无意义的diff），请重新排版：将拆分的行重新合并为每个段落一行。仅在Markdown需要的地方插入换行符：段落之间、列表项之间，以及标题、代码块和表格的前后。
仅在文档需要时使用一个
```
#
```
一级标题。
不得跳过标题层级。
将模糊的标题替换为具体的标题。
- 反面示例：
```
## Overview
```
- 更好的示例：
```
## How the retry queue handles failed payments
```
- 重命名标题会破坏其锚点链接：请先检查是否有入站
```
#anchor
```
  链接和目录（TOC）；如果存在，将重命名作为建议标记，而非直接应用。
移除装饰性水平分隔线，除非它们用于分隔不同的文档章节。
在你撰写或重写的文案中，优先使用直引号（
```
'
```
```
"
```
）和连字符或逗号分隔的从句，而非不必要的em破折号（
```
—
```
）——在纯文本中，完美的手工排版反而会显得像机器生成的内容。对于用作文案连接词的箭头符号（
```
→
```
、
```
⇒
```
），例如
```
input → output
```
、
```
problem → solution
```
、
```
renamed → new name
```
，也遵循同样的原则：用文字表述关系（如
```
变为
```
、
```
然后
```
、
```
导致
```
、
```
重命名为
```
），或者在符号更合适的技术文本中使用ASCII格式的
```
->
```
。以下情况请勿改动：代码、命令或围栏代码块内的引号、破折号或箭头；作为正式符号使用的箭头（如图表、状态机、数学或化学表达式、引用的工具输出、指向实际UI的键盘快捷键路径如
```
File → Save
```
）；风格一致且刻意为之的排版类文档（已发布/格式化的文章）；或者引语或专有名词中的符号。绝对不要转换为角引号（guillemets）或任何国家/地区的特有引号风格。这仅针对字符本身，而非含义——不要为了移除破折号或箭头而改动措辞。
对于读者可以计数或验证的数字，使用阿拉伯数字而非文字拼写——例如
```
9 supported sites
```
、
```
4 permissions
```
、
```
2 clicks
```
、
```
12 months
```
——包括0-9的数字以及句首的数字。一组数字和一组文字的视觉形状不同，因此读者在快速扫读跳过周围文字时也能注意到数字（NN/g 眼动研究）；如果用文字拼写，同样的信息就会淹没在句子中。标题、表格单元格和任何单行摘要优先使用阿拉伯数字——这些是读者首先会看到的内容。
- 当数字不是数据时，保留文字拼写：用作代词的
```
one
```
  或固定搭配中的数字（例如「one person, one vote」、「which one」、「one-time code」、「one-click」）、单独的代词搭配（例如「the two agree」、「all three」）、用作修辞的模糊数量（例如「thousands of throwaway profiles」、「by the hundred」），以及零太多而影响可读性的大数（例如「24 billion」，而非
```
24,000,000,000
```
  ）。
- 绝对不要在同一个句子中混合使用两种形式：例如「600 emoji, not six defaults」就是错误的。当修辞性的
```
one
```
  和数字相邻时，改写句子，或者将两者都用文字拼写，而不是一个用数字一个用文字。
- 整个文档使用统一的千位分隔符（例如统一用
```
50,000
```
  ，不要一段用
```
50 000
```
  ，另一段用
```
40,000
```
  ），复合修饰词使用连字符：例如
```
2-day-old post
```
  、
```
6-digit code
```
  。
- 印刷风格指南对1-9的数字有相反的规定（AP风格会拼写一到九，Chicago风格会拼写一到一百），因为这些是印刷规则。如果文档声明了内部风格，或者作者运行了带有
```
style-guide
```
  参数的
```
awesome-grammar-check
```
  ，则以该声明为准——请说明你应用了哪条规则。
移除过多的粗体。仅对UI标签或必要的强调内容使用粗体。
将小型表格转换为文案，除非表格包含可对比的数据。
仅对有序步骤使用有序列表。仅对真正并列的内容使用无序列表。
折叠「Key Takeaways」、「In Summary」和「Conclusion」类章节，除非它们包含新信息。

Pass 3: Language cleanup

第3步：语言清理

Remove filler, inflated importance, and generic AI-like phrasing.

Prefer:

Concrete nouns over abstract labels.
Active voice over passive voice.
One precise verb over stacked modifiers.
Specific evidence over “experts say”, “studies show”, or “many believe”.
Short direct transitions over polished signposting.

Watch for and rewrite:

Filler adverbs of ease: “simply”, “just”, “easily”, “obviously”, “of course”
“It is important to note that...”
“In today’s fast-paced landscape...”
“This comprehensive guide explores...”
“plays a crucial/pivotal/key role...”
“underscores/highlights/showcases...”
“robust/seamless/cutting-edge/innovative...”
“not only X but also Y”
“from X to Y” ranges used for drama rather than meaning
forced groups of three
vague positive endings such as “the future looks bright”
prose narrating its last revision instead of the current state — “has been updated to”, “now uses”, “previously” (fine in changelogs and migration guides)
summary-stamp openers as a move (any label announcing a summary before delivering it: “In conclusion”, “Here’s the TL;DR:”), and redundant plain-language restatement (“in other words…”, “put simply…”) that repeats an already-made point
circular/tautological definitions (“the system enables users to use the functionality”) and noun stacking (“production-ready deployment system infrastructure”)

That list is the working bar for this pass. If

awesome-humanize-en

is installed alongside, its

references/language-patterns.md

extends it with the wider filler and cliché catalog, and

references/structural-style-patterns.md

(#16) covers the em-dash, arrow-glyph and bold-overuse policy behind Pass 2 — both with false-positive boundaries. Neither is required to finish this pass.

移除填充词、夸大重要性的表述以及通用的AI式措辞。

优先使用：

具体名词而非抽象标签。
主动语态而非被动语态。
一个精准的动词而非堆叠的修饰语。
具体证据而非「experts say」、「studies show」或「many believe」这类表述。
简短直接的过渡而非华丽的引导语。

注意并改写以下内容：

表示轻松的填充副词：“simply”、“just”、“easily”、“obviously”、“of course”
“It is important to note that...”
“In today’s fast-paced landscape...”
“This comprehensive guide explores...”
“plays a crucial/pivotal/key role...”
“underscores/highlights/showcases...”
“robust/seamless/cutting-edge/innovative...”
“not only X but also Y”
“from X to Y” 这类用于渲染效果而非表达实际含义的范围表述
生硬的三点式罗列
模糊的正面结尾，例如“the future looks bright”
叙述上一版本修订而非当前状态的文案——例如“has been updated to”、“now uses”、“previously”（在更新日志和迁移指南中是合理的）
作为铺垫的总结式开头（任何在给出总结前先宣布总结的标签：“In conclusion”、“Here’s the TL;DR:”），以及重复已有观点的冗余通俗重述（“in other words…”、“put simply…”）
循环/同义反复的定义（例如“the system enables users to use the functionality”）和名词堆叠（例如“production-ready deployment system infrastructure”）

以上列表是本步骤的执行标准。如果同时安装了

awesome-humanize-en

技能，其

references/language-patterns.md

文件包含更全面的填充词和陈词滥调目录，

references/structural-style-patterns.md

（#16）则涵盖了第2步背后的em破折号、箭头符号和粗体过度使用规则——两者都包含误判边界。完成本步骤不要求必须安装这两个文件。

Pass 4: Specificity and source discipline

第4步：具体性与来源规范

For every paragraph, ask:

What concrete fact, instruction, example, or decision does this add?
Could this paragraph apply unchanged to 100 other documents?
Does the sentence claim more than the source or context supports?
Does it assert causation without evidence (post-hoc)? "Launched in Q3, so adoption rose" is a logic error — either supply the proof ("adoption rose 25% the next month, driven by the onboarding change") or downgrade to correlation. This is a repair that adds evidence, never a hedge.
Is the heading specific enough for a reader scanning the page?
Are names, filenames, variables, and section labels unambiguous?
Will this content drift? Screenshots, UI step lists, and hardcoded version numbers go stale fastest — flag them with a TODO comment if you cannot verify they are current.
Would a scanning reader find the answer in 15 seconds? Check the headings, code-block placement, and the first 100 words.

Intentional style deviations are not errors: sentence fragments in marketing copy or a deliberately punchy register may be the author's choice — ask before normalizing them.

If a paragraph adds no concrete information, delete it.

If a claim is too broad, narrow it.

If a source is missing, add:

<!-- TODO: source needed for this claim. -->

Do not hide uncertainty behind polished prose.

针对每个段落，自问：

这段内容添加了什么具体的事实、说明、示例或决策？
这段内容是否可以原封不动地套用到其他100份文档中？
这个句子的论断是否超出了来源或上下文的支撑范围？
它是否在没有证据的情况下断言因果关系（事后归因）？例如「Launched in Q3, so adoption rose」就是逻辑错误——要么提供证据（例如「adoption rose 25% the next month, driven by the onboarding change」），要么降级为相关性。这是一种补充证据的修复，而非模糊其词。
标题是否足够具体，让扫读页面的读者能快速理解？
名称、文件名、变量和章节标签是否明确无歧义？
内容是否会过时？截图、UI步骤列表和硬编码的版本号最容易失效——如果你无法验证它们是否最新，用TODO注释标记它们。
扫读的读者能在15秒内找到答案吗？检查标题、代码块的位置以及前100个词。

刻意的风格偏离不属于错误：营销文案中的不完整句子或刻意简洁有力的语气可能是作者的选择——在调整为规范风格之前先询问作者。

如果某个段落没有添加任何具体信息，删除它。

如果某个论断过于宽泛，缩小其范围。

如果缺少来源，添加：

<!-- TODO: source needed for this claim. -->

不要用华丽的文案掩盖不确定性。

Pass 5: Output format

第5步：输出格式

Never hard-wrap paragraphs to a fixed width (see Pass 2): one paragraph is one line. If the input arrives already hard-wrapped, reflow it to that style — do not preserve the broken wrapping.

Before delivering, re-check that later passes did not undo earlier ones (e.g. a Pass 3 rewrite re-introducing a hard-wrapped line, a filler opener, or a placeholder).

If editing files:

Modify the Markdown file directly.
Return a concise summary of changes.
Mention any TODOs or source gaps.
Do not include a long explanation of your editing process.

If editing pasted text:

Return the cleaned Markdown.
Then add
```
## Editorial notes
```
with at most six short bullets.
Do not include generic praise.

If the user asks for an audit trail:

Return a change table
```
# | Original | Correction | Reason
```
instead of prose notes, separating objective fixes (artifacts, broken structure) from subjective suggestions (wording), so the author can accept or reject each edit.
Lead with the top 3–5 highest-impact fixes (label them Critical / High / Medium) above the full table, so the author fixes what matters first.

绝对不要给段落设置固定宽度的硬换行（见第2步）：一个段落就是一行。如果输入的文档已经是硬换行的，重新排版为这种风格——不要保留错误的换行。

交付前，重新检查后续步骤是否撤销了前面步骤的修改（例如第3步的改写重新引入了硬换行、填充式开头或占位符）。

如果是编辑文件：

直接修改Markdown文件。
返回简洁的修改摘要。
说明所有TODO项或来源缺失。
不要包含冗长的编辑过程说明。

如果是编辑粘贴的文本：

返回清理后的Markdown。
然后添加
```
## Editorial notes
```
章节，最多包含6个简短的要点。
不要包含泛泛的赞美。

如果用户要求审计轨迹：

返回一个
```
# | Original | Correction | Reason
```
格式的修改表格，而非文字说明，将客观修复（痕迹、结构损坏）与主观建议（措辞）分开，以便作者可以接受或拒绝每一处编辑。
在完整表格上方，首先列出影响最大的3-5项修复（标记为Critical / High / Medium），以便作者优先处理重要内容。",