Google开发人员帮助文档编写指南，深入理解优秀文章撰写标准

google

该文档是谷歌官方为开发人员在编写技术文档时提供的写作指南，目的是让开发人员写出统一的、易于理解的、利于用户体验的技术文档。通过该指南，可以看出谷歌对优秀文档的标准，理解并应用好这些标准，不论是写技术文档还是写其他任何文章，对文章整体优化与体验都有较大帮助。

原文地址：https://developers.google.com/style/

原文为英文版，以下为列举翻译文中要点。

首先：需要避免的一些描述方式

  • 专业术语或行话。
  • 不稳重。
  • 带有主观情绪。
  • 占位符短语，如“请注意”、“此时”。
  • 臃肿的难以理解的长句。
  • 用相同的短语开始所有句子（例如“你可以：”或“ 操作：”）。
  • 流行语。
  • 以客户，竞争对手或其他任何人为代价的笑话。
  • 感叹号，除了罕见的真正激动人心的时刻。
  • 古怪用语。
  • 过分的比喻。
  • 与主题没有密切关系，或者需要大量的题外信息或模糊的信息。
  • 带有诋毁和侮辱的语句。
  • 用 我们 而不是你。
  • 一再强调简单或容易。
  • 网络俚语与口语，或不常见的互联网缩写。

内容描述：

  • 未发布的内容不要在文档中透露，避免发布后信息不一致。
  • 使用标准的美式英语写法，写短而清晰的句子。始终如一。避免使用缩写。不要使用太多的修饰符。澄清因果。不要过于具有文化特色。不要使用网络用语，网络流行词。
  • 使用标准美国大写字母，使用句子作为标题。
  • 不要用人的行为去比喻电脑及软硬件，比如：不推荐： PC看到一个新设备。推荐： PC检测到新设备。
  • 先描述内容或目的，后放置链接或如何执行。比如：不推荐：点击[这个链接]，查看更多详细信息。推荐: 查看更多详细信息,点击[这个链接]
  • 使用链接(内链或外链)来引导读者了解相关信息，通常，交叉引用链接到非文章所讲的必要信息，但这能增加读者的理解。
  • 确保代词清楚地指代其前因。不推荐：将此设置为true。建议：将此值设置为true。
  • 使用“你”而不是“我们”。在文档中使用第二人而不是第一人 - “你”（有时是隐含的）而不是“我们”。不推荐：让我们点击立即提交 。不推荐：我们现在点击 提交。稍微好一些：您现在单击“ 提交”。推荐：点击提交。

标点符号：

  • 冒号：冒号表示紧密相关的信息如下。当冒号引入列表时，冒号前面的文本必须能够作为完整的句子单独存在。当冒号前面的文本为粗体时，冒号也应加粗。
  • 省略号：一般情况下，不要使用省略号。如引用非必要材料，较长时使用省略号。当材料包含一个或多个句子边界时，请使用四个点而不是三个点，在省略号之前和之后插入一个空格，除非标点符号紧跟省略号; 在这种情况下，请勿在省略号后插入空格。
  • 感叹号：不要在文本中使用感叹号，除非它们是代码示例的一部分。
  • 句号：用句号结束​​一个完整的句子，除非这是一个问题。
  • 分号：使用分号分隔独立子句。比如：如果您没有时间，那么请关注最有益处的改进：对您的用户最重要的是什么; 什么是最重要的修复; 以及在可用时间内修复的容易或可行的方法。
  • 斜杠：避免在文件路径和URL中使用斜杠。不推荐： 3/4 推荐： ¾ 、 0.75 、 75％

格式化：

日期和时间：一般情况下，将月份和星期用单词缩写表示，（如：星期，月份 日， 年份）。在12小时制表达时间时，应加上大写的AM或PM。不推荐: Mon, September 3, 2018 。推荐: Mon, Sep 3, 2018

图像：使用SVG文件或压缩的PNG图像; 使用 figure 元素; 不要使用该 height属性; 提供alt替代文字；提供高分辨率的图像。

标题：对headi和title使用句子形式，而非关键词。

列表：对有序的内容使用列表如：ul、ol、li、dl、dt、dd。

  1. ol， li：按顺序执行的步骤顺序，有小写字母或小写罗马数字
  2. ol class= upper-alpha ，li ：可供选择的选项，尤其是互斥选项。
  3. ul， li：既不是序列也不是选项的项目集。
  4. dl，dt，dd：一组术语，每个术语都有描述，定义或解释。

空格：在句子之间只留一个空格。 在数字和单位之间放置一个不间断的空格。

指定测量单位时，请在数字和单位之间使用不间断空格。

不推荐： 64GB

推荐： 64＆nbsp; GB

推荐： 2＆nbsp; TB

但是，当计量单位是金钱，度数或百分比时，不要留空间。

表格：用表来表示相关数据集。

文件名：使用全小写，并用连字符分隔单词。通常，单独的单词用连字符，而不是下划线。在文件和目录名称中仅使用标准ASCII字母数字字符。

推荐的： avoiding-cliches.jpg

一般： avoiding_cliches.jpg

不推荐： avoidingcliches.jpg， avoidingCliches.jpg，avoiding-clichés.jpg

产品名称：尽量使用产品全程，而不是它们的缩写。

HTML格式：

  • 不要使用制表符来缩进文字; 仅使用空格。因为不同的文本编辑器以不同方式解释选项卡。
  • 每个缩进级别缩进2个空格。
  • 对元素和属性使用全小写。
  • 不要在行尾留下空格。
  • 链接文字：使用对读者有帮助的描述性链接文本即锚文本，在某些法律文件（例如某些服务条款文档）中，可以将URL用作锚文本。
  • 如果您在链接之前或之后有标点符号，请尽可能将标点符号放在链接标记之外。特别是，在引号标记之外加上引号。
  • ID或Name值：对id及name值使用小写，并在单词之间加上连字符。
  • img元素中的URL引用，对于同一域名下的图片的引用，使用站点根目录相对URL。 img src= /shared/images/arrow-24.png
  • 对于同一域名下的所有链接，请使用站点根目录相对URL。当链接到同一域名下的另一个页面时用 / ，即使链接放与被链接放位于同一目录中 。
  • 非同一域名下，引用时尽可能的使用“https”

举例：

不推荐：想要更多？<a href="/wombats">点击此处！</a>。

不推荐：想要更多？阅读<a href="/wombats">本文档</a>。

推荐：有关详细信息，请参阅<a href="/wombats">护理和喂养您的袋熊</a>。

 

不推荐：请参阅<a href="http://www.w3.org/Protocols/rfc2616/rfc2616.html"> http://www.w3.org/Protocols/rfc2616/rfc2616上的HTTP / 1.1 RFC. HTML </A>。

推荐：请参阅<a href="http://www.w3.org/Protocols/rfc2616/rfc2616.html"> HTTP / 1.1 RFC </a>。

 

不推荐（HTML版本）： <h2> <a name="Introduction_To_Everything">一切介绍</a> </ h2>

可接受（HTML版本）：<h2 id="introduction-to-everything">Introduction to everything</h2>

推荐（HTML版本）：<section id="introduction-to-everything"> <h2>Introduction to everything</h2> ... </section>

 

不推荐：有关详细信息，请参阅<a href="#Test">“测试代码”。</a>

不推荐：有关详细信息，请参阅"<a href="#Test">测试代码</a>"。

示例域名和名称

你可能偶尔需要提供域名，电子邮件地址，人名，公司名称或电话号码等虚构示例。在许多情况下，最好使用占位符变量，例如 user-id或email-address，但在某些情况下，您可能需要特定的示例。

域名示例

如果你在示例中需要通用域名，请使用example.com，example.org或example.net。

电子邮件地址示例

如果您在示例中需要通用电子邮件地址，请使用用户名少于六个字母的Gmail地址。Gmail不允许小于6个字符的用户名，因此这种方法可确保您不会意外地提供真实的用户名。例如，您可以使用[email protected]或[email protected]。

如果你需要通用的非Gmail地址，请使用“示例域名”中列出的某个域，如：[email protected]。

人名

当你需要人名时，可以使用不受版权保护的虚构角色。 不要使用受版权保护的虚构角色，也不要使用真人姓名。

你也可以起虚拟名字，注意虚拟名字需包含多种形式，以反映现实世界的多样性。以避免暗示只有某些群体（如白人或亚洲男性）具有技术技能。

公司名称示例

需要公司名称实例时，可使用Example Organization。如果你需要区分两个不同的虚构公司，可以在公司名称中添加说明。例如，你可以使用Enterprise Example Organization和Startup Example Organization。

电话号码示例

如果要显示示例电话号码，可使用（800）555-0100 至（800）555-0199范围内的美国号码。该范围电话号码用于保留实例使用。切勿在示例中使用真实的电话号码。

IP地址示例

当您在示例中需要IP地址时（例如在日志中），可使用为提供文档目的的RFC 5737地址 。这些地址不在Internet上使用。具体如下：

192.0.2.1

198.51.100.1

203.0.113.1

对于地址范围，可使用以下示例：

192.0.2.0/24

198.51.100.0/24

203.0.113.0/24

你可能感兴趣：

Totop