文档可以成就或毁掉一个产品。
根据2022 年数据库状况调查，文档是开发人员决定使用哪个数据库的第二重要因素。在2017 年 SciPy 会议的一项非正式调查中，受访者平均认为开发人员应该多花 20% 左右的时间在文档上。
最终用户知道文档很重要。开发人员知道文档很重要。为什么感觉好文档这么难找？
部分原因在于，文档通常是根据用户身份而不是他们使用文档的方式来组织的。
错误的角色
我在一家数据库公司工作。当我想到我们的用户时，我会想到：
- 软件工程师
- 开发运维工程师
- 数据库管理员
- 数据工程师
- 数据分析师
- 数据科学家
…等等。
这是一种自然的方法。
但是在参加了我们的文档网站的用户测试会议之后，我确信基于角色的角色是错误的方法。用户的职位不提供有关他们将如何使用文档的信息。
但注意用户与文档的交互方式，您将开始看到模式的出现——在规划和组织文档方面，这些模式比职位名称更有用。
重要的三个角色
这些年来，我使用文档的方式并没有太大变化。
我喜欢先建立一个心智模型。我通读了任何介绍性材料，如果有可用的教程，并运行一些示例，所有这些都是在我开始解决我正在处理的任何问题之前完成的。
但并不是每个人都是这样。
在2007 年 Dagstuhl 研讨会论文集上发表的一篇简短文章中，Steven Clark 讨论了在 Microsoft 一年中观察软件工程师最终用户（想想 API 和 SDK 的最终用户）如何带领他的团队开发三个角色：
- 系统开发人员更喜欢在使用技术之前先了解它。他们倾向于防御性编码并寻求优雅的解决方案。
- 投机取巧的开发人员主要关心解决业务问题。他们寻求实用的解决方案，并且更愿意在不查阅文档的情况下试验产品。
- 务实的开发人员介于系统开发人员和机会主义开发人员之间。他们有条不紊地编码，寻求可靠的解决方案，并倾向于在探索的同时使用文档。
我是一个务实的开发者。你是哪一个？
在2019 年的一项观察研究中，梅塞堡应用科学大学的研究人员指出，“我们将参与者分类为机会主义或系统性开发人员似乎并不能预测一般的编程经验或领域相关背景知识的可用性。”
这与 Clarke 自己的观察是一致的：“我们在角色中描述的工作风格为具有不同专业水平和教育背景的人所共有。并不是说某人一开始是机会主义的开发人员，然后在获得成功后成为务实的开发人员。一定程度的经验和专业知识。”
现在我正在关注人们实际使用文档的方式，这与我自己的经验和观察是一致的。
我一直在为错误的角色写作。
对内容设计的影响
好的文档建立在实用的、独立的示例的基础上。
务实和系统的开发人员将使用更长的文档，例如教程和概念指南。但是投机取巧的开发人员对阅读一千字的解释兴趣不大。
一个可靠的例子为所有角色提供了一个很好的切入点：
机会主义的开发人员可以试验和扩展示例以快速构建解决方案。系统和务实的开发人员可以使用该示例作为基础来探索有关产品的更多信息并建立他们的理解。
一个很好的例子：
- 自包含：用户可以复制、粘贴和运行它而不会出错，包含安装说明或明确链接，或者用户可以在托管环境中打开示例。
- 实用：它展示了用户将遇到的真实情况，并且可以很容易地适应其他情况。
- 警告用户任何陷阱：它包括有关可能无法预料的行为的重要信息或在多种做事方式之间做出决定的指导。
投机取巧的开发人员可能永远不会超越示例。提供指向更多资源的明确链接可以满足务实和系统的开发人员的需求，同时又不会让投机取巧的开发人员被过多的信息扼杀。
尽管这三个角色更适合弄清楚如何组织和呈现信息，但旧角色——围绕职位头衔组织的角色——仍然有用。
他们激发切入点。
想让别人使用您的文档？找到针对他们需求的第一个很好的例子。让它独立，这样他们就可以毫无摩擦地使用它。提供更多资源的慷慨链接。
然后使该入口点易于找到。
深入挖掘
在这本透彻且发人深省的书中，从多位行业资深人士的经验中学习。这是所有开发人员的必备读物。
可从亚马逊购买。
