Back to Details

writing-style

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing style

写作风格

Technical prose in this repo follows the Google developer documentation style guide, condensed below. The goal is plain, direct writing that does not read as AI-generated.
Exception: pages under 
mintlify/legal/
are verbatim text provided by Legal. Do not restyle them; change them only as instructed, word for word.
本存储库中的技术散文遵循Google开发者文档样式指南（下文精简版）。目标是使用朴素、直接的语言，避免读起来像AI生成的内容。
例外情况：
mintlify/legal/
下的页面是法务提供的逐字文本。不要重新调整样式；只按指示逐字修改。

Sentences

句子

  • Active voice. Name who does the action: "Grid retries the payout", not "the payout is retried". Passive is fine when the actor is irrelevant ("the quote expires after 30 seconds").
  • Second person for instructions: "you", not "we" or "the user".
  • Present tense: "the webhook fires when the transaction settles", not "will fire".
  • Condition before instruction: "To receive status updates, register a webhook", not "Register a webhook if you want status updates". Same for links: "For supported currencies, see X", not "See X for supported currencies".
  • One idea per sentence. Short sentences, but complete ones. No fragments for effect.
  • Say it once and stop. Cut any sentence that restates the previous one.
  • 使用主动语态。明确动作执行者：“Grid重试支付”，而不是“支付被重试”。当执行者无关紧要时，被动语态可以接受（“报价在30秒后过期”）。
  • 指示使用第二人称：“你”，而不是“我们”或“用户”。
  • 使用现在时：“当交易结算时，webhook触发”，而不是“将触发”。
  • 条件在前，指示在后：“要接收状态更新，请注册webhook”，而不是“如果你想接收状态更新，请注册webhook”。链接同样如此：“支持的货币，参见X”，而不是“参见X以获取支持的货币”。
  • 每句一个想法。使用短句，但需完整。不要为效果而使用碎片化句子。
  • 说一次就停。删掉任何复述前一句的句子。

Words

词汇

  • Plain words over jargon and buzzwords. Name the actual endpoint, field, status, error code, or currency, not "the system" or "the workflow".
  • Never "simply", "just", "easy", or "quickly" in instructions.
  • No placeholder phrases: "please note", "at this time", "it's worth noting", "keep in mind".
  • No figurative language, metaphors, or pop-culture references.
  • Introduce a term once, then use it consistently. Don't rotate synonyms for variety.
  • 使用朴素的词汇，而非行话和流行语。直接说出实际的端点、字段、状态、错误码或货币，而不是“系统”或“工作流”。
  • 指示中永远不要用“简单地”、“只是”、“容易”或“快速”。
  • 不要使用占位短语：“请注意”、“目前”、“值得一提的是”、“请记住”。
  • 不要使用比喻、隐喻或流行文化引用。
  • 引入一个术语一次，然后一致地使用。不要为了多样性而替换同义词。

Formatting

格式

  • Sentence case for titles and headings.
  • Numbered lists only for ordered steps; bullets for everything else. One concrete behavior per bullet.
  • Serial comma.
  • Code font for endpoints, fields, values, and commands. Bold for UI elements.
  • Link text describes the destination ("see the quote lifecycle"), never "click here" or a bare "here".
  • Unambiguous dates (2026-08-19 or "August 19, 2026").
  • No exclamation marks.
  • No em-dashes. Use commas, periods, parentheses, or restructure the sentence.
  • 标题和标题使用句子式大小写。
  • 数字列表只用于有序步骤；其他情况使用项目符号。每个项目符号一个具体行为。
  • 有序列逗号。
  • 端点、字段、值和命令使用代码字体。UI元素使用粗体。
  • 链接文本描述目标（“参见报价生命周期”），不要用“点击此处”或裸“此处”。
  • 明确的日期（2026-08-19 或 “2026年8月19日”）。
  • 不用感叹号。
  • 不用破折号。使用逗号、句号、括号或重构句子。

Content

内容

  • Write for a reader who was not in the working session. No shorthand or codenames invented while drafting; spell out what happens.
  • Don't document unreleased or future behavior. Describe only what the API does today.
  • Paste real request/response bodies and error payloads in code blocks; never paraphrase what the API returns.
  • State trade-offs directly: "chose X over Y because Z". No hedging, no selling.
  • Structure follows the content: add a heading or bullet list only when there are genuinely multiple items.
  • Lead with the conclusion or the change; background after.
  • No summary or conclusion sections that restate the page.
  • 为未参加工作会议的读者写作。不要使用起草时发明的简写或代号；说明发生了什么。
  • 不要记录未发布或未来的行为。只描述API当前的行为。
  • 在代码块中粘贴真实的请求/响应体和错误负载；永远不要转述API返回的内容。
  • 直接说明权衡：“选择X而非Y，因为Z”。不要含糊，不要推销。
  • 结构跟随内容：仅在确实有多个条目时添加标题或项目符号列表。
  • 以结论或变更开头；背景放在后面。
  • 不要添加重述页面的摘要或结论部分。

PR descriptions and review comments

PR描述和审查评论

  • PR descriptions say what changed and why, in complete sentences, one behavior per bullet. The test plan states what was actually run.
  • Review comments open with the point ("nit:", "question:") and quote the specific line or output. One finding per comment. Frame a suggestion as a question when the author may know something you don't.
  • PR描述说明变更内容和原因，使用完整句子，每个项目符号一个行为。测试计划说明实际运行了什么。
  • 审查评论以要点开头（“nit:”、“question:”）并引用具体行或输出。每条评论一个发现。当作者可能知道你不知道的事情时，将建议表述为问题。

De-AI pass (run last, on every draft)

De-AI检查（最后，对每一份草稿执行）

  • No AI jargon or grand framing: "first-class", "end-to-end", "robust", "seamless", "leverage", "holistic", "comprehensive", "battle-tested".
  • No punchy fragments for effect: "No more X.", "The result? Y.", "Simple."
  • No "It's not X, it's Y" constructions, rhetorical questions, or triadic flourishes ("faster, safer, simpler").
  • If a sentence could open a product blog post, rewrite it as a statement of fact.
  • 不要使用AI行话或宏大框架：“first-class”、“end-to-end”、“robust”、“seamless”、“leverage”、“holistic”、“comprehensive”、“battle-tested”。
  • 不要为了效果使用冲击性碎片：“No more X。”、“The result? Y。”、“Simple.”
  • 不要使用“It's not X, it's Y”结构、反问句或三连修饰（“faster, safer, simpler”）。
  • 如果一个句子可以打开产品博客文章，将其改写为事实陈述。