敏捷方法论赋能技术文档写作：实时文档的最佳实践
浏览：0
巴克励步
我经常和产品团队的同事聊文档管理，发现一个普遍困境：要么文档写得像百科全书，没人看；要么干脆不写，后期维护成本爆表。其实，好的文档策略应该是“恰到好处、即时生成”——这正是敏捷文档的理念。很多人误以为敏捷就是不要文档，但实际恰恰相反：它要求我们在正确的时间、用正确的方式产出必要的内容。对于需要持续迭代的产品手册或知识库来说，敏捷方法能显著提升团队效率，避免信息过时。今天我就结合敏捷思想，聊聊如何高效
我经常和产品团队的同事聊文档管理，发现一个普遍困境：要么文档写得像百科全书，没人看；要么干脆不写，后期维护成本爆表。其实，好的文档策略应该是“恰到好处、即时生成”——这正是敏捷文档的理念。很多人误以为敏捷就是不要文档，但实际恰恰相反：它要求我们在正确的时间、用正确的方式产出必要的内容。对于需要持续迭代的产品手册或知识库来说，敏捷方法能显著提升团队效率，避免信息过时。今天我就结合敏捷思想，聊聊如何高效建设产品手册，让文档真正为产品增值。
PWC的一项研究表明，敏捷产品的成功率比传统产品高出28%。
这对软件和产品开发来说很棒，但相关的文档写作呢？
实际上，许多公司已经成功地将敏捷原则应用于技术文档写作，我们将向你展示如何做到这一点。
💛🧡🧡客户评价：分析哪些搜索会导致哪些文章（帮助我们磨练我们的content/titles更适合）。
你可能不需要彻底改变文档创建流程；事实上，你反而会简化它。
没错，敏捷鼓励团队在必要时才进行文档编写，且不超过必要的程度。
这种文档方法将为团队节省时间和金钱，同时仍然为用户提供同等有效的资源。
现在，让我们从核心价值观和原则开始，探讨该方法的细节。
敏捷文档方法详解
写得够用、即时生成——这就是敏捷文档方法的精髓。
无论你是软件工程新手还是资深专业人士，你可能都遇到过“敏捷”这个词被应用于从开发到测试的各个环节。
根据Google Trends的数据，这种方法的受欢迎程度多年来一直在稳步增长。
既然这一趋势仍将持续，理解什么是敏捷以及如何将其应用于创建技术文档至关重要。
敏捷方法论的核心是将软件开发组织成更短、迭代的工作周期。
其核心原则在2001年由17位软件开发专家制定的《敏捷宣言》中有详细描述。
然而，当你开始阅读宣言时，你会注意到在将敏捷原则应用于编写技术文档方面可能存在一个潜在问题。
但在我们以表面价值接受“优先考虑软件而非全面文档”这一指南之前，我们应该提醒自己，这两者在最终软件产品中都扮演着角色。
《宣言》并不反对编写技术文档。
相反，它只是指出创建文档的过程不应掩盖项目的实际目的，即向客户和用户提供有效的产品。
换句话说，“写得够用、即时生成”意味着最好记录正在进行的操作，避免为计划中但最终可能不会实现的功能编写可能冗余的文档。
在遵循敏捷方法确定文档创建时机时，关键建议是随着产品开发进度同步编写技术文档，或者至少记下基础内容，让技术写作者后续可以在此基础上构建。
这种做法也符合敏捷的另一个核心价值观：响应变化而非遵循计划。
接受开发计划经常变化的事实，将帮助你编写相关且准确的文档，而不是固守项目开始时设定的可能过时的计划。
希望现在敏捷文档听起来不那么令人生畏了。
你不应让看似复杂的方法论阻止你实践这种有效的技术文档写作方法。
那么，让我们看看如何运用敏捷思维来进行文档编写。
敏捷文档的“什么、在哪里、何时”
正如我们所看到的，在敏捷中不记录所有内容是完全可行的。然而，当你有直接的指导方针可循时，实施该方法会更容易。
因此，我们首先从列出你应该记录什么和不应该记录什么开始。
有一个广泛传播的误解，认为敏捷等于没有文档。这种误解不仅不正确，还可能让你项目经理抓狂，所以请确保不要上当。
实际上，一切都取决于你正在处理的具体项目。
正如我们在关于软件文档类型的文章中所写，并非每个软件项目都需要发布说明和报告。
发布说明可能是过程文档的标准部分，但根据敏捷方法论，这并不足以成为提交一份不能为产品增值的文档的理由。
相反，你应该决定在项目推出之前、期间和之后需要哪些具体文档。
因此，如果创建用户指南能更好地提升产品，那就放弃市场需求文档。
关于在哪里创建文档的问题，指导原则是决定一个存储库，并在那里进行所有更新。
毕竟，你不希望信息分散在Jira、Trello和Google Docs中——这通常是多人团队的常见情况。
选择一个地方构建文档可以防止关键信息丢失。
此外，它使整个团队在整个开发过程中随时可以访问文档，这确实符合敏捷实践。
如果你需要一个单一平台来记录开发过程、创建技术文档，甚至与最终用户共享，Baklib可能就是你的解决方案。
Baklib，我们的产品文档平台，使用提及、标签和链接系统来促进协作。
类似于敏捷宣言所描述的，使用Baklib将帮助你“强调个体和互动高于流程和工具”。
因此，如果你正在寻找敏捷的“在哪里”，Baklib是一个值得考虑的文档存储库。
最后，关于何时编写技术文档的问题，敏捷方法强调即时（JIT）方法。
通过JIT，你可以与产品开发并行创建文档。换句话说，团队编写的是活文档。
这样，你可以简化流程效率，因为技术写作者不必仔细检查那些在新版本发布后已过时的信息——所有信息始终是最新的。
即时阅读（JIT）文档
除了在文档创建方面发挥作用外，JIT文档方法也可以应用于用户阅读文档的方式。让我们一探究竟。
在受敏捷启发的软件开发流程中，术语“即时”指的是与开发同步编写文档，既不提前也不滞后。
这种方法使团队能够将精力集中在紧迫问题上，处理相关事务，确保不会编写不必要的文档。
然而，最终用户也希望高效利用时间。这就是为什么庞大的用户指南正逐渐被更好、可导航的知识库格式所取代。
在上图中，你可以看到TalkChief（一个商务电话系统）创建的用户文档。
正如你所见，产品Wiki不仅显示了整个解决方案的概览。
它还允许用户只关注他们感兴趣的问题和疑问，在他们需要的时候获取，符合JIT原则。
以让最终用户更快找到信息的方式构建技术文档，节省了他们的时间，并降低了产品学习曲线。
因此，在编写文档时，不要忘记内部团队并不是唯一希望快速完成任务的一方，确保最终用户也能即时获取相关信息。
敏捷文档最佳实践
如果有效编写技术文档听起来像你愿意尝试的事情，你可能对如何将敏捷方法应用于写作感兴趣。
为帮助你，我们将回顾我们认为是建立成功敏捷技术写作流程的两个关键最佳实践。
让我们从负责文档的人员开始。
敏捷方法论非常重视团队协作。事实上，团队合作将确保文档包含准确、来自源头的信息。
然而，当工程师、设计师和支持专家都参与文档编写时，事情会变得有些混乱。这就是为什么技术写作者是团队的一个极好补充。
一个便捷的技术写作者招聘方式是在指定平台上发布广告并允许分享，例如Writers Write。
你可能会在那里看到一些熟悉的公司也在寻找技术写作者。
招聘平台让你能够清晰展示你的业务和角色描述，从而提高只有具备相关技术技能的候选人申请的可能性。
一旦你根据申请缩小候选池，不要忘记提出合适的面试问题，以确保为你的团队找到最合适的技术写作者。
写作者将组织并统一所有JIT信息，形成一个整体。
尽管如此，你不应该指望技术写作者解决可能出现的矛盾——最好从一开始就预防它们。
这就是我们第二个建议的原因：尽量保持文档简单。
看看Spotify的故障排除页面，这是简单而有效的用户文档的一个例子。
该页面介绍了一个常见问题，并提供了直接了当的答案。
Baklib是一家知识管理软件公司和解决方案提供商。我们不断投资于我们的知识管理系统，因为我们的客户喜欢它！平台使用一年后，客户保留率超过 85%，我们知道我们一定做对了什么。我们相信，在未来，人类、知识和技术的交汇将为世界上任何地方的任何公司的增长和生产力提供动力。只要安全、准确、可靠地应用人工智能，它就能增强工人的智慧，并改变各行各业的业务。随着我们不断增强和完善我们的平台功能和能力，我们的目标是继续成为世界上最好的知识管理软件公司。
