Google开发人员文档样式指南

为方便查看，使用Google翻译从 Google开发人员文档样式指南搬运而来

一般原则

风格和作者的语气

https://developers.google.cn/style/tone

交谈而不轻浮。

在你的文件中，要有一个对话，友善和尊重的声音和语气，不要过于口语或轻;; 一种随意，自然而平易近人的声音，而不是迂腐的或激进的。尝试听起来像一个懂得开发者想要做什么的知识渊博的朋友。

不要试图写出你说话的方式; 你可能比你应该写更多的口头和口头上说，至少开发文档。但目标是一个会话语气，而不是一个正式的。

不要试图超娱乐，也不要超干。做人，让你的个性展现，令人难忘; 你甚至可以有点搞笑。但请记住，该文档的主要目的是向正在寻找它的人提供信息。

请记住，许多读者不是英语母语人士，他们中的许多人来自不同于您的文化，您的文档可能会翻译成其他语言。

有些事情要尽可能避免

流行语或技术术语。
太可爱了。
“请注意”和“此时”的占位符短语。
啰嗦或冗长的句子。
用相同的短语开始所有句子（如“你可以”或“待办事项”）。
目前的流行文化参考。
以顾客，竞争对手或其他人为代价的笑话。
惊叹号，除了在罕见的真正激动人心的时刻。
贪婪，僵硬和愚蠢。
混淆隐喻或隐喻太多。
有趣的线条与主题没有密切的关系，或者需要大量的主题词，或者模糊信息。
诋毁或侮辱任何一群人的措辞。
用“让我们”来表达一些措辞。
在程序中使用“简单”或“这么简单”或“很容易”等短语，除非是非常简单/容易的程序。

一些技术和方法来考虑

如果你在表达一些东西时遇到困难，请退后问自己：“我想说什么？通常，你给自己的答案揭示了你应该在文件中说什么。
如果你不确定你的措辞或语气，请一位同事来看看。
试着大声阅读你的文件的部分，或至少说话的话。这听起来自然吗？不是每个句子在说话时都必须听起来自然，这些是书面文件。但是，如果你遇到一句尴尬或混乱的句子时，考虑一下你是否可以使它更加交谈。
使用句子之间的转换。像“虽然”或“这种方式”这样的短语可以使段落更加低调。（再次，有时像“然而”或“然而”这样的过渡可以使段落更加高调）。
即使遇到问题，也要确保以清晰直接的方式交流有用信息。这是最重要的部分。

礼貌和使用“请”

礼貌是很好的，但在一组指示中使用“请”是礼貌的过度。

不建议：要查看文档，请点击查看。

建议：要查看文档，请单击查看。

也：

不建议：有关更多信息，请参阅[链接到其他文档]。

建议：有关更多信息，请参见[链接到其他文档]。

例子

太不正式了	恰到好处	太正式了
好家伙！这API是完全可怕的！	这个API可以让你收集你的用户喜欢的数据。	该页面记录的API可以使得能够获取关于用户偏好的信息。
就像一个流行明星一样，这个电话会得到你的“电话”号码。问问别人的数字的简单方法！	要获得用户的电话号码，请致电。user.phoneNumber.get()	电话号码可以由开发者通过简单的get()方法在user 对象phoneNumber属性上使用方法来检索。
然后，BOOM ，就像他们用法语说的那样，只是垃圾收集（或者说集装箱装扮），而你是金的。	要清理，请调用该collectGarbage()方法。	请注意，完成任务需要以下先决条件：执行自动内存管理功能。

记录未来的功能

https://developers.google.cn/style/future

不要在文档中预先发布任何内容。

避免试图记录未来的功能或产品，即使以无害的方式。

可访问的内容

https://developers.google.cn/style/accessibility

撰写不仅可供残疾人士使用的文件，也可向国际受众以及使用旧技术和不同浏览器的使用者提供文件。

使用正确的语法和标点符号。
使用主动语态和现在式。
写清楚，简单的句子。
始终如一。
避免行话，俚语等。

例子

不推荐： API选择器列出了您可能想要做的最常见的事情。

建议： API选择器列出了您可能想要执行的最常见的事情。

使用最简单的术语。
明智地使用颜色：
- 请记住，一些色盲的人不能告诉绿色的红色。
- 确保您的文字颜色与您的背景颜色充分对比。

为全球读者撰写

https://developers.google.cn/style/translation

我们用美国英语编写我们的开发者文档，但其中一些被翻译成英文以外的语言。写在笔记翻译。

几个具体的建议：

写简短的，明确的句子。

句子越短，翻译就越容易。英语比大多数语言短; 平均长度的英文句子翻译时可能会导致很长的句子，影响了理解。

始终如一。

例如，如果您在一个地方使用特定概念的特定术语，则在其他地方使用完全相同的术语，包括相同的大写。如果你使用不同的名字来做同样的事情，翻译者可能会认为你指的是不同的概念，因此可能会使用不同的翻译。

另外，不要用同一个词来表示不同的东西。尤其要避免在近距离使用同一个词作为名词和动词。有关多重含义问题的示例，请参阅单词列表条目一次和以后。

避免缩写。

缩略语可能会混淆背景，而且翻译不好。至少在第一次使用给定的术语时，尽可能地拼出一些东西。

不要使用太多的修饰符。

特别是，不要使用两个以上的名词作为另一个名词的修饰语。

避免错位修饰符。

例如，在与其相关的名词或动词的前面加上“only”或“just”等单词。

不推荐：开发人员只需要申请一个令牌。
建议：开发人员只需要申请一个令牌。

澄清前因。

当译员使用小而不连贯的文本串时，使用代词可能会变得棘手。通过尽可能清楚的事情来帮助他们。例如，如果代词含糊不清，则用适当的名词来代替它。

不推荐：如果您在广告中使用“绿色啤酒”一词，请确保它是有针对性的。

建议：如果您在广告中使用“绿色啤酒”一词，请确保广告有针对性。

不要太具体的文化。

特别是，除非你确定他们是世界闻名的，否则不要提到具体的假期，文化习俗，运动等等。

也避免口语化。诸如“棒球形状”，“背部燃烧器”或“悬挂在那里”这样的短语可能会令人困惑。

语言和语法

缩略语

https://developers.google.cn/style/abbreviations

缩写包括首字母缩略词，初始主义，缩写词和缩写。

首字母缩写词是由短语中的第一个字母组成的，但发音就像是一个词本身：
- 北约对北大西洋公约组织。
- 水肺为自含式水下呼吸器。
初始化也是由一个短语中的第一个字母组成，但每个字母都是分开发音的：
- CIA为*情报局。
- 供参考的信息。
- PR的公共关系。
缩短的单词只是一个单词或短语的一部分，有时在最后一段时间：
- 医生为医生。
- 等对等等。
- 分钟的分钟。
- CA为加州。
收缩在本样式指南的单独页面中讨论。

这些类别之间有一些重叠。具体而言，取决于说话者的偏好，一些缩写可以是缩写词或初始词; 例子包括FAQ和SQL。在某些情况下，发音决定使用“a”还是“an”。

主动语态

https://developers.google.cn/style/voice

明确谁在执行行动。

一般来说，使用主动语态（其中句子的语法主体是进行动作的人或事物）而不是被动语态（其中句子的语法主体是被操纵的人或事物），虽然有例外。

其中一个原因是：在被动语态中，很容易忽略指出谁或什么正在执行特定的动作; 在这种构建中，读者往往很难弄清楚谁该做什么。（读者，计算机，服务器，最终用户，网页访问者......）

例子

不推荐：查询服务，发送确认。

建议：发送一个查询到服务。服务器发送确认。

可以用被动语态（用“by”）来表示谁在执行动作，但是由此产生的散文通常不如将句子重写为主动语态那么好。所以只要有可能，就把这个行为当作句子的主语。

例子

不建议：服务由您查询，并由服务器发送确认。

建议：发送一个查询到服务。服务器发送确认。

拟人论

https://developers.google.cn/style/anthropomorphism

不要将人的品质归因于软件或硬件。

例子

不推荐：定界符对象告诉拆分器应该断开一个字符串的位置。

建议：分隔符对象指定分隔字符串的位置。

不推荐：PC看到一个新的设备。

建议：PC检测到新设备。

文章（a，an，the）

https://developers.google.cn/style/articles

在文档中包含明确和不确定的条款，并正确使用它们。

为了便于理解和翻译，在你的写作中包括一个，一个和一个。

一和的是不定冠词和单数名词之前使用。他们指的是任何一个组的成员。

这是一个明确的文章。它在单数和复数名词之前使用，指一个或多个特定的成员。

是否使用“a”或“an”取决于后面的单词的发音。在辅音之前使用“a”; 在任何元音之前使用“an”。

例子

一小时。
一个HTML文件。
一只手。
一家酒店。
一把雨伞。
工会。

更复杂的是，一些缩写既可以是缩写和initialisms，需要一个在一个实例，一个在其他。例如，常见问题解答，其中一些读“斑”和其他人拼出来，需要的时候拼写和一个当作为单词发音。以下是这些类型缩写的列表，以及我们对哪些文章的使用建议：

一个SQL（数据库）。
常见问题解答

大写

https://developers.google.cn/style/capitalization

在文本中，遵循美国英语的标准大写规则。另外：

不要使用全部大写字母来强调。
请遵循官方名称，品牌，公司，软件，产品，服务等的名称。

注意：有关如何大写特定单词的信息，请参阅单词列表。

标题和标题的大小写

在文件标题和页面标题中，使用句子大小写。也就是说，只是把第一个字大写。

例外：对于专有名词，商标，关键字和其他总是以某种方式进行大写的术语，使用该术语的标准大写，而不管它在标题或标题中出现的位置。

即使你正在使用判例，也不要在标题末尾加上句号。

大写和冒号

使用小写字母开始紧跟在冒号后面的文本的第一个单词，除非文本是以下内容之一：

专有名词
一个报价。
项目符号，编号或定义列表中的项目。
跟在标签之后的文本，例如注意或注释。
与标题相同的行上的副标题。

大写和数字

使用字幕和其他与人物相关的文字。

术语表和索引中的大写

词汇和索引术语使用小写，除非该术语是专有名词，或者有其他原因需要大写。

词汇表定义使用句子。

大写和连字

当一个带连字符的单词是一个句子或一个标题中的第一个单词时，除非后面的单词是专有名词或适当的形容词，否则只用大写单词中的第一个单词。

列表中的大写

对所有类型的列表中的项目使用句子大小写。

文本中表格的大小写

对表格中的所有元素使用句子：内容，标题，标签和标题。

子句顺序

https://developers.google.cn/style/clause-order

在说明之前放置有条件的条款，而不是在之后。

假设你想告诉观众在特定情况下做些事情。如果可能的话，请在提供指导之前提及情况; 这样，如果情况不适用，读者可以跳过这个指令。

例子

不建议：请参阅[链接到其他文档]了解更多信息。