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。
ol， li：按顺序执行的步骤顺序，有小写字母或小写罗马数字
ol class= upper-alpha ，li ：可供选择的选项，尤其是互斥选项。
ul， li：既不是序列也不是选项的项目集。
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”
举例：
不推荐：想要更多？点击此处！。
不推荐：想要更多？阅读本文档。
推荐：有关详细信息，请参阅护理和喂养您的袋熊。
不推荐：请参阅 http://www.w3.org/Protocols/rfc2616/rfc2616上的HTTP / 1.1 RFC. HTML 。
推荐：请参阅 HTTP / 1.1 RFC 。
不推荐（HTML版本）：
一切介绍
可接受（HTML版本）：
Introduction to everything
推荐（HTML版本）：Introduction to everything
...
不推荐：有关详细信息，请参阅“测试代码”。
不推荐：有关详细信息，请参阅"测试代码"。
示例域名和名称
你可能偶尔需要提供域名，电子邮件地址，人名，公司名称或电话号码等虚构示例。在许多情况下，最好使用占位符变量，例如 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
结束语：
全球各大互联网功能，在技术能力的积累也产出很有优秀的技术经验，避免后来者入坑，值得我们学习。这是第一篇，后续会陆续分享，全球各大互联网的技术文档。
一个会思考的胖子
长按扫码关注，分享技术干货，技术资料，个人成长等。