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  GB

推荐: 2  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