乔丹-梅里克敏锐地意识到，让人们阅读文档是多么困难。作为工具开发平台Retool的技术作家，他的工作是为用户创建文档。
"我经常开玩笑说，用户从不阅读文档，"梅里克说。"他们非常没有耐心，他们希望能够尽快尝试产品，而文档是他们认为的障碍。"
让文件更有吸引力的技巧
- 使文件易于查找和阅读。
- 与其他团队成员一起进行文件审查。
- 维护文件，使其始终是最新的。
- 不要浪费时间去记录那些仍在变化中的产品。
- 包括高水平和低水平的文件。
- 让它更具互动性。
- 包括视频和屏幕截图等视觉效果。
- 将文件的重要性植入团队文化。
但是，对于那些撰写文档以帮助他人理解应用程序的设计、功能和架构的开发人员和技术作家来说，这种现象可能是相当令人沮丧的。他们倾注了无数的时间为外部或内部用户编写产品文档，但却发现几乎没有人知道它的存在。而与此同时，用户问的问题正是你在文档中所预期和解决的。这可能会让人士气低落。
"这是一个我们相当清楚的现象，"梅里克说。他说，挑战始终是。"我们如何确保文件尽可能地吸引用户？"
这里有一些让人们真正阅读文档的建议。
文件应易于查找和阅读
有时候，团队把软件文档放在一个不起眼的共享文件夹里，藏在一个很少使用的服务器上，这使问题更加复杂。如果文档难以找到，人们就不可能不顾一切地去阅读它。
将文档存储在靠近代码库的地方是一个不错的选择。它使文档更容易被找到，而且，由于开发者看到的更多，他们也更有可能维护它并保持其最新状态。
"我看到很多公司把他们的文档放在他们的代码旁边--在他们的存储库里面或者在代码文件里面，"技术训练营Tech Elevator的讲师Matt Eland说。
在线房地产平台Opendoor的工程、卖方和B2B主管Heather Natour说，文件的结构也很重要。文档如果非常长，而且不包括方便读者浏览的方法，就会使人们不愿意使用它。
在文档中加入搜索功能是很有帮助的，有一个清晰的文档结构，列出内容，包括高级概述和不同的章节。这样一来，用户就可以浏览与他们相关的信息，而不是被迫通篇阅读。
文件应该有摘要部分，说明文件的目标，Natour说。"[这]可以让人保持对作者去向的理解，并可能跳过去找到他们需要的东西。"
代码审查？试试文件审查。
文档解析公司Mindee的开发者关系主管Frédéric Harper表示，文档通常是由编写代码的工程师在事后编写的。而这可能是一个问题。
"他们做出了这样的假设：'我们不必在那部分进行详细说明，'或者'我们甚至不必解释那部分，'"哈珀说。"考虑一下你的听众。对待他们就像他们对你所谈论的事情一无所知一样。"
"为你的听众着想。对待他们就像他们对你所谈论的事情一无所知一样。"
当文档作者没有得到足够的反馈时，这些信息盲点就会发生。软件咨询公司Value Transformation的软件测试工程师Jon Quigley说，就像代码审查一样，把其他审查者带入文档编写过程是个好主意--最好是在早期，甚至在编写代码时。
"不要让一个人，或只是一个子集的人，来写它，"奎格利说。"每一个被这件事触动的人都应该是制定它的一部分。"
例如，如果一个系统工程师创建了关于一个系统的文档，他们应该从其他以不同方式与软件互动的工程师那里寻求意见。这不仅会使文档对更多的用户更有用，而且也会改善软件本身的设计。
不要让文件变质
用户很快就会无视过时的文档。这是正确的，因为花在阅读过时的文档上的时间大多是浪费的。
"纳图尔说："如果术语发生了变化，或者你引用的东西不再真正适用，读者可能就会完全抛弃它，不使用它。
她说，开发团队应该有一个围绕维护和更新文档的过程，这样就不会给用户造成另一个障碍。
"我们真的注意到，陈旧的[文档]会导致挫折感。而这导致了用户去其他地方。"
在数据查询公司Deephaven Data Labs，工程师们实际上设置了他们的系统，对文档以及代码进行夜间测试，该公司的开发者关系工程师Amanda Martin说。Deephaven为外部用户--他们自己也是开发者--创建文档，所以该公司非常重视文档。
Deephaven的工程师将他们的文档与代码库一起存储在GitHub中，每天晚上都会针对文档中的代码片断实例进行测试。这确保了文档永远不会与他们产品中的代码脱节。
"我们真的注意到，陈旧的[文档]会导致挫折感。这导致用户去其他地方，"马丁说。
虽然不是所有的公司都有资源来对他们的文档进行测试，但开发团队仍应优先考虑尽可能地保持文档的更新。开发人员可以养成在相应的代码修改后更新现有文档的习惯。
不是所有的产品都需要同样水平的文件
人工智能消息平台Connectly的软件工程师Andreas Nomikos认为，有可能有太多的文档。他说，如果产品仍在变化中，花大量时间在详细的文档上可能没有意义。
"在产品团队中，通常代码库的变化速度太快了，" Nomikos说。"在文档方面投入大量的时间并不能产生良好的投资回报，因为你可能正在构建一些东西，而这些东西在六个月内就会发生变化。"
在这些情况下，对新的开发人员使用更多非正式的培训和入职方法，通常是一个更好的策略。刚加入一个项目的开发者可以通过与更有经验的开发者结对编程来学习，并从事简单的任务，让他们了解代码库。这不需要那么多的维护和时间来设置。
Nomikos说，如果另一方面，开发人员正在创建一个由公司的许多其他团队使用的共享资源，那么投资于文档就更有意义了。例如，基础设施团队创建了内部使用的产品，并且多年来都没有改变。在这些情况下，开发人员应该投入更多的精力来创建清晰和详细的文档，因为许多用户将需要长期参考同一个文档。
好的文件应该解决 "为什么 "的问题
开发人员需要各种文档风格以适应不同用户的需求。
"马丁说："每个用户都带着不同的背景进入该软件，而且往往有不同的目标。
有些人想要一个高层次的概述，了解该软件的作用以及它与其他工具的比较，而其他用户是开发人员，他们寻找低层次的指南，列出他们正在调用的某些功能的输入和输出。例如，当Eland使用Dotnet的机器学习库时，他既参考了低层次的技术文档--他称之为 "参考式文档"，也参考了解释整体设计的高层次文档。如果他只使用参考式文档，他很容易迷失方向。
"它们看起来都有相同的重要程度，因为它们都在同一个名单上，而且都是按字母顺序排列的，"埃兰说。"我不知道该先钻研哪一个。"
但相反，如果他从阅读高层次的文件开始，比如 "入门 "页面，它可以作为一个目录，澄清项目的目的，并指向他的额外资源。特别是对于这些高层次的文件来说，抓住原因很重要。如果用户通过阅读文档能够理解开发者对其应用的愿景，那么他们将更有可能理解具体实现的特殊性，这些特殊性可能会脱离背景而显得很奇怪。
这甚至可以简单到列出系统指标--通过让读者了解一个应用程序的能力，可以帮助他们建立一个关于该应用程序可以做什么的心理模型。
让文件更具有互动性
一些对开发者来说最有效的文档是互动的，允许读者跟着编码来帮助吸收信息。仅仅有文字会使开发者不愿意使用它。
"开发者，我们是有行动力的人，我们想编码，我们想让事情发生，"哈珀说。"当我可以直接去编码和尝试时，我为什么要去看文档和阅读所有的东西？"
持续文档公司Swimm的联合创始人Tom Ahi Dror说，代码耦合文档既包括解释性文字，也包括对代码库的引用，可以使原本沉闷的参考文档变得更加生动。"他们要么解释代码，要么用代码的片段作为例子"。
"开发者，我们是行动派，我们想编码，我们想让事情发生......。当我可以直接去编码和尝试的时候，我为什么要去看文件和阅读所有的东西？"
他的公司，Simm，专门创造工具，使开发者更容易将他们的文档与代码联系起来。详细的技术文档的链接直接出现在代码编辑器中，代码的链接也出现在文档中。开发人员在编写文档时可以采取类似的策略，在文档的文本中加入链接和代码片段，使读者更容易理解。
在Retool，梅里克说他通常的目标是编写互动式文档，可以让用户在五到十分钟内创建一些简单的东西。
"他说："这种成就感增加了参与度和信心，以至于用户很想了解更多--在这种情况下，他们将更多地参与到文档中。
他说，在创建交互式文档时，选择简单的、现实世界中用户可能实际遇到的例子很重要。
"梅里克说："建立产品的真实世界用途更有吸引力，因为用户可以更容易地将他们的需求映射到用例上。他鼓励开发者创建互动练习，如旋转客户关系管理工具或仪表盘。
利用视觉和视频的优势
好的视觉效果和视频也能为枯燥的文档增色。Eland说，使用Markdown编写文档的开发者可以利用该语言的特点，将链接、视频和图片直接嵌入到文档文件中。
"很多可能需要几段话来描述的事情--或者你可以录制一个快速的GIF或YouTube视频，"埃兰说。"人们看到它就会说，'嗯，好的，这很有意义。"
基于文本的文档也有优势，比如可搜索性，但同时包括视觉和文本对于以不同方式学习的人来说是非常有帮助的。视频和截图甚至不需要花很长时间来创建，实际上可以节省开发者的时间。
"Natour说："我的团队中的一位工程师快速录制了他们在调试一个特定类型的问题时的情况，它只是降低了创建和分享信息的障碍。"能够以一种可重复使用的快速视频格式获得这些互动的好处，真的很有帮助。它只是让人们更容易参考。
培养文件的文化
不管项目的文件编制有多好，决定文件是否被使用和维护的大部分因素是开发文化。Quigley说，这种文化可以通过在最后期限紧迫和关键问题出现需要关注时，文档是否真正被优先考虑来衡量。
团队可以制定一个政策来编写需求文档，有一个仔细的设计审查过程，甚至做文档审查。但是，如果团队每次在项目有时间压力的时候都不顾这些考虑，那么这些政策就不会维持太久。
这就是为什么管理者应该通过优先考虑文档，并在开发周期中总是挤出时间来更新和维护现有的文档来促进文档文化--无论情况如何。
"Quigley说："如果你没有把文化搞好，那么你说的其他东西或放在白纸黑字上的东西都不会有意义。