Back to Details

writing-guidelines

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

writing-guidelines

writing-guidelines

Write for a reader who is busy and did not see your work. Readability beats cleverness; clarity beats completeness.
为忙碌且没有看到你工作过程的读者而写。可读性胜过卖弄；清晰胜于完整。

Rules

规则

  • Lead with the outcome. The first sentence answers what happened or what the thing is - the line the reader would ask for if they said "just the TLDR". Supporting detail comes after.
  • Cut filler. Delete "just", "simply", "basically", "in order to", "it is important to note". If a sentence changes nothing when removed, remove it.
  • Concrete over abstract. Name the file, the number, the command. "Faster" is weaker than "cuts the build from 40s to 9s".
  • Active voice, one idea per sentence. Short sentences that each carry one point read faster than long ones that carry three.
  • Consistent terms. Use the project's own vocabulary, the same word for the same thing every time. Tie names to the shared-language 
    CONTEXT.md
    when one exists (see 
    domain-modeling
    ).
  • Readable, not clipped. Being short and being clear are different. Achieve short by dropping what the reader does not need, not by compressing prose into fragments, arrow chains (
    A -> B -> fails
    ), or invented abbreviations.
  • 先讲结果。 第一句话回答发生了什么，或说明事物是什么——也就是读者说“只要 TLDR”时想要的那一行。支撑性细节放在后面。
  • 删减填充内容。 删除“只是”“简单地”“基本上”“为了”“需要注意的是”。如果删除某个句子后意思毫无变化，就删掉它。
  • 具体优于抽象。 写出文件名、数字和命令。“更快”不如“将构建时间从 40 秒缩短到 9 秒”有力。
  • 主动语态，每句话只讲一个观点。 每句话只传达一个要点的短句，比一句话塞入三个要点的长句读起来更快。
  • 术语保持一致。 使用项目自己的词汇，同一事物始终使用同一个词。如果存在共享语言文件 
    CONTEXT.md
    ，将名称与其关联起来（参见 
    domain-modeling
    ）。
  • 易读，而不是被截断。 简短和清晰并不相同。应通过删除读者不需要的内容来变短，而不是把文字压缩成残句、箭头链（
    A -> B -> fails
    ）或自造缩写。

Error messages and UI copy

错误信息和 UI 文案

  • Say what happened and what to do next: 
    Config not found at ./app.config.ts. Create it or pass --config <path>.
    beats 
    Error: config missing
    .
  • No dead ends. Every failure names a next step.
  • Match the product's voice; drop exclamation marks and filler enthusiasm.
  • 说明发生了什么以及下一步该做什么：
    Config not found at ./app.config.ts. Create it or pass --config <path>.
    优于 
    Error: config missing
    。
  • 不留死路。每次失败都要指出下一步。
  • 符合产品的语气；去掉感叹号和填充性的热情用语。

AI-slop tells to strip

需要去除的 AI 写作痕迹

  • Em-dashes and en-dashes - use a spaced hyphen or a full stop. This is the most reliable machine-written tell.
  • Hollow openers: "In today's fast-paced world", "It's worth noting that".
  • Hedging stacks: "might potentially perhaps".
  • Binary flourishes: "Not X. But Y." as a rhetorical beat.
  • Over-structured lists where a sentence would do.
  • Em dash 和 en dash——改用带空格的连字符或句号。这是最可靠的机器写作标志。
  • 空洞的开场白：“在当今快节奏的世界中”“值得注意的是”。
  • 模糊限定词堆叠：“也许可能或许”。
  • 二元式修饰：“不是 X。而是 Y。”，把它当作修辞节拍。
  • 过度结构化的列表；其实一句话就够。

Output

输出

When editing, show the tightened version and, on request, a one-line note per change. Do not pad the edit with praise for the original.
编辑时，给出精炼后的版本；如有要求，再为每项改动附一行说明。不要用对原文的赞扬来填充编辑结果。