作者：Tammy Xu
Jordan Merrick 深知让人们阅读文档有多难。作为工具开发平台 Retool 的技术写作人员，他的工作就是为用户创建文档。
"我经常开玩笑说用户从不读文档，"Merrick 说。"他们非常没有耐心，想要尽快试用产品，而文档被视为实现这一目标的障碍。"
让文档更具吸引力的技巧：
文档应该易于查找和阅读
将文档存储在靠近代码库的位置，是取代晦涩共享文件夹的好方法。这使文档更容易被找到，而且由于开发人员能更频繁地看到它，他们也更可能去维护它。加入搜索功能和清晰的结构，列出内容并提供高层次概览，让用户可以快速浏览相关信息。
代码审查？试试文档审查。
就像代码审查一样，把其他审查者引入文档编写过程是个好主意——理想情况下是在早期，甚至是在代码编写的同时。"不要只让一个人，或者只让一小部分人来写，"Jon Quigley 说。"所有与这件事有关联的人都应该参与其开发过程。"
不要让文档过时
用户很快就会忽略过时的文档。开发团队应该建立维护和更新文档的流程。在 Deephaven Data Labs，工程师们每晚对文档和代码都进行测试。"我们真的注意到，过时的文档会导致挫败感。这会导致用户转而寻找其他地方。"
并非所有产品都需要同等程度的文档
Connectly 软件工程师 Andreas Nomikos 认为文档可能过多。"在产品团队中，代码库的变化速度通常太快了。在文档上投入大量时间并不会带来好的投资回报，因为你可能正在构建的东西在六个月内就会改变。"
好的文档应该解答"为什么"
有些人需要高层次的概述，而其他用户是寻找低层次指南的开发人员。"每个用户带着不同的背景进入这个软件，通常也有不同的目标。"加入"入门"页面可以作为目录，阐明目的并指向其他资源。
让文档更具互动性
"开发人员，我们是行动派，我们想编写代码，想让事情发生。当我可以直接去编码和尝试时，为什么我要去读文档？"与代码耦合的文档——既包含说明性文字又有对代码库的引用——可以为原本枯燥的参考文档增添活力。
培育文档文化
"如果你搞不好文化，那么你说的或写下的其他任何东西都不会有价值，"Quigley 说。管理者应该通过在开发周期中始终留出时间来更新和维护现有文档——无论情况如何——来推动文档文化建设。
