敏捷文档：方法与最佳实践
敏捷文档遵循《敏捷宣言》原则，与软件开发同步，强调“足够好”的最小可行文档，通过紧密协作、同步发布等提升客户体验与业务敏捷性，包含范围、规格等要素，采用规划、协作等步骤及简洁等最佳实践。
什么是敏捷文档？
敏捷是一种轻量级框架，它帮助个人、团队和组织通过为复杂问题提供适应性解决方案来创造价值。敏捷文档是指遵循敏捷宣言中设立的原则来制作文档的实践。技术写作者与软件开发人员紧密合作，按照开发人员的节奏和冲刺周期来准备产品文档。
技术文档适应了包括站会、冲刺计划和回顾在内的敏捷仪式。所有的经验教训都在产品负责人和产品经理之间共享。在产品文档团队内部采用敏捷宣言的原则，能够补充产品功能并提供完整的产品体验。
文档在敏捷软件开发中的重要性
敏捷宣言阐述了敏捷软件开发过程的基本原则，例如：
- 个人和互动高于流程和工具
- 可工作的软件高于详尽的文档
- 客户合作高于合同谈判
- 响应变化高于遵循计划
然而，这份宣言对具体实施方式持开放态度，因此在敏捷软件运动初期，许多人采用了不同的方法。在众多公司经过数年的实验和采用敏捷软件开发方式后，出现了许多趋同的最佳实践。客户关注是敏捷宣言的核心主题，因为软件是解决客户业务问题的方案。
敏捷方法论持续聚焦于客户的业务需求，并确保构建一个最小可行产品作为解决方案。为了支持敏捷软件解决方案，每个软件版本都应附有相应的文档。在敏捷软件发布周期中，敏捷文档的重要性可以总结如下：
- 软件与文档应同步发布，以最大化客户体验。
- 敏捷文档流程可补充软件开发，助力业务敏捷性。
- 文档团队与软件开发人员采用相同的敏捷方法论与流程，有助于团队实践的一致性。
- 敏捷文档流程为与软件开发人员更紧密协作奠定基础。
- 敏捷文档还能帮助减少客户实现价值的时间，通过准确的文档整体性地利用软件解决方案。
- 向客户传达技术信息，以最大化产品价值。
- 合规/监管机构要求技术文档作为软件产品的一部分。
创建敏捷文档时应思考的3个问题
运用敏捷方法论创建文档是一门可以随时间掌握的艺术。在创建敏捷文档时，你需要思考三个重要问题。
1. 应该产出什么文档？
确定“做什么”是文档团队的首要任务，因为产品负责人通常只向文档团队和开发人员传达“为什么”。经验丰富的敏捷文档团队通常有一个关于“做什么”的框架，因为这取决于文档服务的目的是什么以及它需要涵盖什么。敏捷文档中著名的“做什么”框架是Diataxis。
在敏捷文档方法中，Diátaxis框架能让人整体性理解文档用户在与软件产品交互周期中的需求。Diátaxis框架在敏捷文档生命周期中易于应用。
在理解敏捷文档的“内容”时，您需要问的主要问题是：
项目开始前需要什么文档？
Diátaxis 框架有助于回答这个问题，因为文档的类型取决于其服务的目的。教程、操作指南、参考资料和技术说明需要针对其目标受众采用不同的写作风格。这些需要在冲刺开始前确定。
项目期间需要何种文档？
在敏捷冲刺期间，由于客户需求仍在不断演变，软件开发的范围可能会发生变化。在冲刺过程中，文档团队可能需要更改正在编写的文档。根据范围变更或冲刺范围的微小调整，所需的文档类型也会有所不同。
产品部署和实施后需要何种文档？
如果敏捷冲刺的范围没有改变，那么最终的文档将不会发生变化，因为计划交付的内容将被实现。然而，如果冲刺范围发生了变化，那么软件部署后的最终文档可能会有所不同。在这种情况下，持续改进过程是敏捷文档不可或缺的一部分。
2. 文档存放何处？
文档工作流对于确保产出符合客户期望、质量达标且技术准确度高的文档至关重要。文档应能被所有利益相关者，特别是客户，在每个冲刺阶段结束时特定产品功能发布后访问到。
易于访问的文档位置
可以使用任何符合敏捷文档方法的、基于SaaS的知识库解决方案来起草文档。敏捷文档的常见存放位置是知识库站点/文档站点，所有与产品相关的文档都在此发布。客户知道这个位置，因为软件产品内部的链接通常会指向这里。有时，应用内帮助也会显示产品文档所在的位置。
文档仓库
如果敏捷文档使用类似Git的系统来构建文档，将可访问的文档保留在一个可以频繁更新的仓库中也是有益的。在这种情况下，文档站点是使用静态站点生成器平台（如Jekyll或Hugo）生成的。
3. 何时选择敏捷方法？
如果文档需要与软件开发同步进行，敏捷文档的效果最好。这类似于制造领域的准时化生产技术。大多数软件开发都在敏捷环境中进行，因此敏捷文档适用于大多数软件开发。敏捷文档不适合以下情况：
💛🧡🧡客户评价：选择Baklib的原因： Baklib因其价格和事实上，它提供了具有自定义选项的全面解决方案，无需切换我们的整个支持系统。
- 使用传统瀑布模型进行软件开发的团队
- 独立工作且可能不以客户需求为导向的软件团队
- 无需在发布周期内发布产品文档
敏捷文档中需包含的关键要素
轻量级的单页项目文档可以成为敏捷文档流程的一部分。以下列表概述了敏捷文档需要涵盖的关键要素：
项目范围
需要简要描述技术文档应涵盖的内容，以满足客户的期望。因此，文档应做到简洁、精确且技术准确。
规格说明书
如果软件功能面向的是高度技术性的受众，一份涵盖技术规格/需求的技术规格文档会非常有用。
合规性条件
如果文档需要满足任何合规性条件，应详细说明。这适用于医疗产品、制造、石油和天然气行业。
生产支持文档
如果软件产品分阶段发布，则文档也应为不同的产品环境和系统设置而发布。这包括为不同的产品版本以及不同的产品阶段（如Alpha、Beta和GA）发布不同的文档。
最终用户指南
除了技术文档外，可能还需要为任何合作伙伴/经销商提供关于产品技术配置的技术指南。这类文档可能不会与最终用户共享。
培训手册
一款直观的技术文档软件，可轻松添加您的内容并将其与任何应用程序集成。试试 Baklib 吧！
如何在敏捷开发中进行技术文档编写
以下是制作技术文档涉及的详细步骤。
规划您的敏捷文档
规划敏捷冲刺是敏捷文档的第一步。产品负责人和项目经理通常会设定敏捷冲刺的目标。这有助于理解敏捷文档的工作范围。用户故事在冲刺规划会议期间起草，并为每个用户故事分配负责人。文档团队在冲刺规划期间进行任务分解。
开发人员和其他敏捷团队成员可以在冲刺期间为文档工作做出贡献。这可以加速文档的开发。在每日站会期间，每位文档团队成员将更新他们的任务。Scrum Master将根据依赖关系来协调任务管理和任务优先级排序。
在展示活动中，文档团队可以展示他们已构建的文档，并与利益相关者分享。
参加冲刺回顾会议，分享"哪些做得好"、"哪些需要改进"以及"哪些需要停止"。Scrum Master通常会记录这些内容，并为持续的流程改进奠定基础。
一个清晰的产品待办事项列表，可以帮助文档团队根据产品路线图来优先安排工作精力和时间。这有助于进行一些战略规划，而不是仅仅管理战术计划。
编写敏捷文档的最佳实践
由于许多技术写作人员正在将敏捷流程应用到文档工作中，起草敏捷文档的最佳实践仍在不断涌现。一些最佳实践总结如下：
- 仅包含最简且相关的信息
- 识别用户及文档的特定目标
- 采用基于测试的方法来定义需求
- 避免构建全面的信息（保持简洁）
- 对文章进行嵌套（树状视图）
- 务必清晰地阐述内容
- 所有成果物均源自单一来源
- 客户知晓可通过搜索引擎查找文档
- 与广泛的利益相关者协作
延伸阅读： 什么是 IT 文档：类型、示例与模板
总结
敏捷文档化为文档团队提供了大量机会，使其能够专注于客户的业务需求，并有助于最大化产品体验。敏捷文档化可以从敏捷宣言中汲取许多启示，并将大多数敏捷实践融入其日常活动中。采用敏捷文档化的最佳实践有助于在软件团队中培育文档文化，从而推动产品导向的增长。敏捷文档化还有助于实现无缝的产品体验，使产品和文档被视为一个整体，而非分离的实体。
延伸阅读： 为您的客户创建卓越的 SaaS 产品文档
如果你准备好测试用于创建敏捷文档的写作工具，请立即试用Baklib。Baklib在一个地方汇集并组织你团队的所有文档、专业知识和项目需求。为你的团队创建一个共享的知识库，使他们能够访问文档和数据。让你的团队准备好在一个敏捷环境中工作，通过实时的准确文档来节省时间并防止错误。
Baklib帮助中心支持多主题模板样式、权限管理、协同管理、多级栏目分类、多端适配、支持富文本和Markdown编辑、可绑定独立域名、api接口调用相关数据、可接入百度统计、友盟、51LA、可接入客服系统，如美洽、udesk等，还有数据统计功能，帮助中心的关键词搜索日志及用户的搜索相关数据可在后台查看。
