Google开发人员文档样式指南

时间:2022-12-26 23:16:25

为方便查看,使用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

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

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

例子

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

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

不建议:如果要删除整个文档,请单击“ 删除”。

建议:要删除整个文档,请单击删除。