米奇·赫德伯格（Mitch Hedberg）说：“当您在好莱坞而且是喜剧演员时，他们希望您除了喜剧之外还能做其他一切。 他们说，好的，你是一个喜剧演员。 你会演戏吗 你能写吗？ 给我们写一个脚本！ …这不公平。 好像我是个厨师，我努力工作成为一个好厨师，他们说，好吧，你是个厨师……你能种田吗？”
如果您是负责编写技术文档的开发人员，那么您可能会有点像Mitch写笑话时的样子。
在今天的帖子中，我们将讨论为何拥有优质的产品文档很重要，以及开发人员在创建产品时有时会面临的独特挑战。 为了帮助您入门，我们将介绍写得很好的文档的一些核心原则，包括如何创建技术风格指南。 太好了-我们将立即让您耕种。
优质用户文档的重要性
在一个完美的世界中，您只需要开发非常易于使用的应用程序和工具，甚至不需要用户文档。 不幸的是，几乎从来没有这样。 即使您认为您可能已经在银河系中发布了最简单，最直观的产品（某人某处），也不会得到它 。 并且不可避免地会有人成为您的用户之一。
1.它提高意识。
使用成熟的内容优化技术的格式正确的文档可能会对您网站的自然搜索流量产生重大影响。 搜索者通过在搜索结果中找到相关的技术文档来了解解决方案的情况并不少见。 一些用户自下而上地解决问题-搜索他们的特定用例或问题，并希望问题已经解决。 技术指南，博客文章和文档将有助于激发和吸引您的目标受众。
2.鼓励收养。
出现问题时，反馈研究表明，三分之二的人更喜欢自助服务。 在Google时代，互联网用户期望即时访问他们想要的信息。 他们希望您已记录了他们的问题，用例或问题。 如果他们甚至需要花一分钟时间写一封电子邮件，开始聊天，发送一条推文或在GitHub上发表评论，那么从字面上看，这可能会决定他们决定使用您的产品，也可能会破坏他们的决定。 更糟糕的是，如果他们认为您的文件伪劣或缺乏，那会让他们对您的产品或品牌产生负面印象。
3.减少流失。
即使是通常跳过“什么是……？”和“入门”部分的高级用户，也经常需要访问参考文档。 可能大多数开发人员都会同意，他们记住的东西越少越好。 能够快速调用参考文档可以节省宝贵的时间（和理智）。 如果他们不喜欢您的文档，那是他们开始寻找替代方案的另一个原因。
4.它收集反馈并捕获数据。
在某人使用您的帮助文档时从他们那里收集的反馈非常有见地。 即使他们使用的文档不能回答他们的问题，他们也处于主导地位和思维定势，可以为您提供有关他们的特定问题或所寻求信息的详细信息，您可以用它来帮助改进您的下一个发行版。
如果您有权访问Web分析，则可以使用访问者数据来帮助制定开发决策。 例如，如果90％的访问您的帮助文档的人正在使用特定的操作系统或浏览器，那么也许该是时候看看造成差异的原因了。 您可以按术语使用相对页面访问量和搜索量来形成有关人们如何使用您的应用程序以及哪些领域可能需要更多关注的可验证理论-无论是从文档角度还是从产品本身。
5.推广您的项目/品牌。
就像我们前面提到的那样，拥有高质量的可索引文档可以帮助您的应用程序广受欢迎。 在某些情况下，您的支持文档将成为用户对您的产品的第一印象。 这样，您的支持文档便可以兼任着陆页。 如果您的文档结构混乱，难以阅读或丑陋，则会对您的品牌产生不良影响，并可能破坏您转换/采用的机会。
6.它有助于优化您的客户服务资源。
如果您是新的或相对未知的开发机构，则在开发过程中和发布时的支持联系量可能会非常低。 如果您的项目起步并变得受欢迎（那是您想要的，对吗？），您自然会开始看到更多联系进入支持渠道。 您会很快意识到，在开发阶段可能已经习惯的个性化的一对一支持流程是无法扩展的（除非您有大量的时间和金钱来聘请和雇用全职员工，服务支持团队）。 拥有完善的文档资料可以作为一种接触偏斜技术，帮助您充分利用（可能是有限的）人力资源，并使您重新专注于开发。
编写文档的挑战
为了帮助您产生良好的文档，我们应该研究开发人员在将文字放在页面上时遇到的一些常见问题。 通过识别潜在的陷阱，您将有能力在看到它们时识别它们，并（希望）避免它们。
1.您不会受到写作的启发。
我们知道了。 您并没有在烹饪学校里呆过这么多年，只是为了成为一名农民。 不幸的是，缺乏兴趣或多年的经验使许多开发人员无视其文档义务或完全忽略了它们。 阅读时，您可以分辨出不良，毫无灵感的作品，听众也可以。 这里没有太多建议……如果提供良好的文档是您成功策略的一部分，是要获得启发并做出适当的努力，还是找到愿意的人。
2.您太接近工作了。
如果您要记录自己在做的事情，那么对它的看法可能会歪斜，并且与项目“同住”的时间越长，则无法客观地描述它的机会就越大。 别感到难过-凡是沉迷于特定主题的人都会自然地发生。 良好的技术写作需要确定在输入客观性的同时，谁会阅读您的内容。
稍后，当我们谈论开发您的风格指南时，我们将开始确定您的受众。 了解您的读者是谁- 他们已经知道什么以及他们如何思考 -将是弄清楚您的特定文档需要达到高低级的重要关键。
3.您没有时间/内容更改太频繁。
对于交付期限很紧的开发人员以及处理频繁的代码或快速，敏捷开发引起的功能更改的技术作者而言，这可能是一个特别具有挑战性的问题。
设置可重复的编辑过程以概述，草稿，审阅，更新和发布内容可以帮助减轻所涉及的一些时间开销，而充实的样式指南可以通过消除一些格式化方面的猜测来帮助加快工作速度一条内容。
什么是样式指南？
如果您来自网络设计背景，那么“样式指南”可能听起来并不像。 它与类，背景颜色或类型大小无关。
样式指南是为特定出版物撰写的规则，实践和准则的集合。 它们用于新闻报导，学术论文，商业通讯和法律文件等内容。 您可能已经听说过美联社使用的AP风格书或MLA手册，这通常用于学术出版。
尽管样式指南中的某些内容是硬性规定，但它不能解决编写文档时可能出现的所有可能出现的问题。 一个好的样式指南可以通过在这些情况下提供更多通用的“指南”来弥补这些极端情况。
随着您的文档不断发展和壮大，您需要在弹出的新问题中加以解决。 这意味着您的风格指南永远不会真正“完成”。 大多数指南都是“活着”的资源。 对于在较长的时间内进行大量技术文档编制的团队来说，维护和更新其样式指南将是一项持续的任务。
为什么需要样式指南？
1.提供目的和方向。
好的风格指南可以帮助作家入门，并在作家有疑问或不确定如何在过程中解决特定问题时提供指导。 无论其应用如何，大多数技术文档都具有相同的总体目标： 告知读者。 简而言之，他们提供知识 。
这与诸如登陆页面（其目标可能更注重行动（例如要求注册））或博客帖子（其目标通常是产生流量/页面视图）之类的东西截然不同。
这似乎是一个明显的区别，但是当开始实际制作内容的时间到时，定义明确的任务将在编写文档的早期阶段为您提供帮助，并且在以后进行更新时可以作为指导性参考或内容质量审核。
就像我们前面提到的，编写技术文档需要一定程度的客观性。 如果您是开发人员（或什至只是较大团队的一部分），可能会很想使用市场营销型语言来描述特定功能的“简便”或“快速”。 尽管这种消息传递有其时间和地点，但用户浏览您的技术文档时，发现它充其量是无济于事的，而最糟的是令人讨厌的。
2.它为您的文档提供一致的外观。
在大多数情况下，您的用户将在您的站点上访问多个不同的技术文档。 通过保持一致的样式，您可以“培训”读者如何最好地使用您的文档。 通过在文档中以相同的方式设置某些元素的样式，您可以减少读者的认知工作来查找他们想要的内容。 例如，通过在介绍之后始终将“代码示例”放在蓝色框中，熟悉您样式的用户将自然而自然地知道如何找到它。
样式指南有时会设置复制的格式规则。 如果您曾经阅读过帮助文档，并且注意到某些操作词始终是粗体的，或者特定变量或值始终是斜体的，则这些准则可能已在发布者的样式指南中建立。 此类微妙的上下文线索可帮助读者快速关注和理解其内容。
他们说您不应该根据封面来判断一本书，但是您的用户将根据其帮助文档来判断您的应用/项目。 您的技术文件介绍应反映公司的其他部分。 用商务语，您的文档是否“适合企业形象”？ 如果他们的格式不正确且结构松散，他们甚至可以在没有机会为您提供服务或应用之前关闭用户。
3.它给您的文档一个统一的声音。
即使您的文档是由不同的贡献者创作的，它们听起来也应该都是由同一个人制作的。 这是专业的，可以使您的内容拥有权威。
4.节省您的时间。
在编写技术文档时，可能会有无数的术语，首字母缩写词和专有名称会定期被引用。 PayPal中的第二个P是否大写？ 我们是拼写“创建”，“读取”，“更新”，“删除”，还是只能说CRUD ？ 对于人类来说，记住所有这些太多了，因此对于此类事件提供快速的一站式参考将节省时间。 随着您的客户服务团队的成长，制定样式指南将帮助您培训新技术作家。
5.解决争端。
好吧……技术作家之间的纠纷。 如果一群人都在写相同类型的内容并试图听起来像同一个人，那么最终在如何设置特定元素的样式或使用特定单词/名称/缩写时将存在一些分歧。 在这些情况下，详尽的样式指南可以作为仲裁者，并在没有明确规定的规则的情况下提供“指导”。 制定（或下达）决议后，可以将新规则或惯例正式添加到指南中。
如何制作样式指南？
1.确定目标受众。
这一个因素可能比其他任何信息都对您的技术著作有所帮助。
如果您是一名开发人员，那么您可能至少对最终使用您的产品的人以及扩展其文档的类型有所了解。 诸如此类的轶事和行业洞察力可以很长的距离来决定制作消息的级别。
网络流量分析工具（例如Google Analytics（分析））可以通过使用硬数据来识别用户的技术细节（例如他们的操作系统，浏览器，他们来自何处，引用他们的人以及他们搜索了哪些字词），从而将这一步骤更进一步。因为它们使它们登陆了您的网站）。
如果您有现有的用户社区，则也可以对他们进行轮询以获取有价值的市场研究信息。
在弄清楚读者是谁时，有几个问题要问自己（和听众）：
他们已经知道了什么？
他们是学生还是刚开始使用，还是具有预先专家水平的知识的高级软件工程师？ 文档的高级程度（或补救性）通常取决于读者的技术专长。
他们想要/期望/需求什么样的内容？
这可能与第一个问题密切相关。 他们是否正在寻找快速入门，以便可以在无需大量阅读投资的情况下开始使用/构建自己的产品？ 他们是否想要深入了解您的解决方案如何运作的所有细节？ 他们只是想要一个简单的值表，可以将其添加为书签或打印为备忘单吗？
他们如何访问您的文档？
这似乎不太明显，可能需要一点想象力。 例如，如果您要记录如何使用已创建的新标记验证工具，那么您可以放心地假设大多数用户都可以从台式机或笔记本电脑上舒适地从办公室或客厅中访问文档。房间沙发。
但是，如果您要记录如何对移动应用程序进行故障排除，则可能意味着大多数用户将通过手机访问您的文档。
2.确定目标。
您的风格指南应有明确的任务或目标。 它对您和您的项目应该是唯一的，但是总的来说，它将是这样的：“此样式指南的目标是鼓励创建遵循既定标准并且在样式，格式，声音和风格上始终一致的技术文档。词汇。”
就像我们前面提到的，技术文档的简化目标是提供知识 。 为此，在提出样式指导目标时，也可能会考虑一下您的目标不应该是什么。
您的目标应该是：
- 能够创建一致的内容
- 协助技术作家
- 充当格式化和样式决策的“真理之源”
您的目标不应是 ：
- 宣传/冠军您的应用/项目
- 说服用户使用您的应用/项目
- 提供发展选择/决定背后的推理
- 轻视比赛
3.创建一个模板。
相似的文档应具有统一的结构。 样式指南提速生产并确保质量的方法之一是提供模板或格式良好的技术文档示例。 为了帮助您开始集思广益，下面是一个简单的示例，说明技术文档模板从上到下的形状。
- 目录 —该文件的组织方式是什么？
- 简介 -我们涵盖了哪些内容，为什么它对读者很重要？
- 要求 -读者需要什么入门？
- 分步演练 -完成任务的确切，详细步骤是什么？
- 示例 —我们是否为想要“动手”的读者提供了一个有效的示例？
- 常见问题解答 -使用此文档或执行此任务时，是否有任何常见的跟进或相关问题？
- 相关文档 —与此文档一起通常引用其他任何现场技术文档吗？
- 其他资源 -读者还能在哪里寻求更多帮助？ （社区链接，第三方文档）。
4.创建一个单词列表。
许多领域和主题都有自己的词汇。 整理与项目相关的常用单词，短语，首字母缩写词和专有名称的列表。 关于如何以及何时使用该单词，规定首选的拼写，大写字母和其他规则。 这将有助于促进文档之间的一致性，并在不同作者之间达成共识。
随着您习惯了自己的样式并使其成为第二天性，您的单词表最终可能会成为样式指南中最常用的工具。 一旦放置在合适的位置，请考虑定期将单词列表添加到本地拼写检查字典中。
5.迭代，然后迭代更多。
就像我们之前讨论的那样，样式指南从未真正完成。 当您开始编写文档，分析数据，收集反馈并进行更正时，将为您提供增加和改进样式指南的机会。 最好定期安排对样式指南的审核，以找出差距并确保其仍在提供最新，正确的样式建议，这是一种很好的编辑做法。
结论
您面向公众的文档可以是您的用户对项目的第一个介绍。 它应该是品牌上的，有用的，直观的，易于阅读的，并为用户提供明确的指导。 创建和维护样式指南将对确保文档以这种方式编写并保持这种方式大有帮助。 最后，样式指南与其他任何开发工具一样，都可以从中获得所用。现在，开始做饭。
