基于规模化敏捷开发流程下的技术文档编写与内容管理
基于规模化敏捷开发流程下的技术文档编写与内容管理
以医疗器械软件用户文档为例
沈晚双 杨悦明 张雅瑾
医科达（上海）科技有限公司
随着软件行业技术的高速发展，面向软件用户的技术文档作为技术传播的重要手段之一，在软件的开发与使用中起着越来越重要的沟通桥梁作用，是用户正确了解和使用产品的重要途径。面向用户的技术文档在与用户沟通方面发挥着不可忽视的作用，为了更快速准确地回应用户的需求，软件开发现采用敏捷的框架，以用户需求为核心，小量快速地发布新功能。这种全新的开发模式对技术文档部门的工作提出了新的要求。如何在规模化敏捷开发框架下转换思路，更好地融入开发团队，及时准确地发布技术文档，是技术文档工程师们面对的议题。
本文从医科达的技术文档部门文档工程师的视角出发，介绍了在规模化敏捷开发的框架下文档部门在与研发团队沟通和协作方面的理论与实践经验，分析了此做法的成效与优势，并希望能对相关企业实践具有借鉴意义，以此引发有关该领域的进一步讨论与研究。
关键词： 软件开发 技术文档 规模化敏捷
1.背景介绍
1.1 关于医科达
医科达是全球领先的专注为全身肿瘤和脑部疾病提供放射治疗解决方案的国际化公司。总部位于瑞典斯德哥尔摩，自1972年成立以来，通过医疗技术的持续创新，不断引领行业发展的新高度。医科达以“助力医生 呵护生命”为使命，致力于改善、延长及挽救患者生命，为全球用户提供精准、智能、高效的放射治疗解决方案和肿瘤信息管理系统。目前，医科达已服务于全球6000多家医疗机构，每天为超过10万名患者提供诊疗方案。
医科达在瑞典、英国、中国等设立研发和生产中心，在全球拥有40多个分支机构，业务范围涉及120多个国家和地区。医科达有限公司在纳斯达克集团斯德哥尔摩证券交易所(NASDAQ Stockholm)上市。
医科达自1982年进入中国，30多年来，始终致力于为中国用户提供精准、智能、高效的肿瘤放疗解决方案和全生命周期售后服务，在中国放疗领域获得极大的信任和认可。在中国TOP50医院的放疗设备中，成为业内公认的放疗领导者。
医科达（上海）科技有限公司主要为医科达在医疗、人工智能、软件开发应用等科学技术方面开展研发工作。公司有软件开发，测试，产品专家，研发科学家等百余名研发人员参与医疗软件的研发维护。其工作内容涵盖了医疗计划软件（TPS），肿瘤信息系统（OIS），以及影像系统等多条产品线。
1.2 关于技术文档部门
技术文档作为技术传播的重要手段之一，在软件的开发与使用中起着重要的沟通桥梁作用，是用户正确了解和使用产品的重要途径之一，是产品集里不可缺少的重要组成部分。技术文档部门的工程师通过与各开发团队协作，了解产品研发最新动态，结合用户视角对新功能进行编辑，为用户提供清晰可读的技术文档。
医科达的技术文档部门承担着撰写、审核、发布、维护用户文档的重要职责，负责的产品包括用户使用文档、发布说明、在线帮助文档、缺陷列表等。这些文档产品缩短了产品与用户之间的距离，使得用户可以清晰地了解医科达研发产品的特点、新功能及未来发展趋势，并可以根据文档清晰地定位到符合用户需要的部分，及时解答使用过程中产生的疑问，是连接用户与产品研发沟通的桥梁之一。
在公司内部，技术文档部门的文档工程师与各开发团队构成合作关系，致力于为团队开发的产品及时准确地交付用户文档，是产品功能开发和维护过程中的一分子。
1.3 关于敏捷
随着软件行业的发展，基于详尽的需求分析、系统设计和把需求变更作为梦魇的瀑布模式已经逐渐被开发者们所丢弃了，而能够更快地面向市场、更好地响应客户需求变更的敏捷开发模式深得开发者们的青睐［1］。2001年，一批软件专家成立了敏捷联盟，他们总结出了能快速高效研发并能轻松应对需求变更频繁的价值观和原则。与传统的软件开发模式不同，敏捷的开发模式强调接受变化，快速更进，以小步快跑的方式实现最小单位的可交付物的实现。针对软件开发过程中的变动，敏捷方法的策略是在整个项目过程中减少变动的成本。旨在开发与变动同步进行，以实现对市场需求和产品优化的最快反应。敏捷开发思想实际上指以人作为核心，根据用户不断变化的需求采用迭代、循序渐进的方法进行灵活开发的一种轻量软件开发方法[2]。
敏捷的开发方式重视当前的代码，在当前的代码的基础上真实可靠地产出项目可交付物。在敏捷的方式下，沟通与交流，特别是面对面的沟通与交流，是最重要的项目推进方式。在敏捷的开发模式下，技术文档部门的工程师，即技术文档工程师，也需要采取相对应的工作模式，跟上敏捷快速的步伐，实现文档内容的实时更新，保证准时交付，反映最新的变更。
敏捷有如下4条价值观[3]：
• 个体和互动高于流程和工具
• 可运行的软件高于详尽的文档
• 客户合作高于合同谈判
• 响应变化高于遵循计划
本文所讨论的Scrum是一种常用的敏捷开发方法，适用于几乎所有的产品开发和管理工作。Scrum开发方法由Ken Schwaber 和Jeff Sutherland 提出，名称来自英式橄榄球，表示“并列争球”［4］。每名队员都保持着对赛场全局的控制和判断，团队整体对变化做出及时的反应，以求实现胜利。正如一个敏捷团队（Scrum team），每一位成员都保持着对当前开发进度的控制和判断，团队整体能够对需求的变化做出及时的反应，并保证持续改善。团队共进退，快速有效地实现符合用户新需求的产品新功能的研发与发布。
Scrum包括3个工件，即产品需求列表（Product Backlog）、迭代待办列表（Sprint Backlog）和产品增量（Increment）。产品需求列表用于存放和管理产品的需求。迭代待办列表用于存放和管理规划到当前Sprint即将开始做的需求。增量是指一个 Sprint结束时开发团队完成之前所承诺的所有迭代待办列表项内的总和，以及之前所有 Sprint 所产生的增量的价值总和。Scrum包括3个关键角色，即产品专员（Product Owner）, Scrum主管（Scrum Master），和开发团队（Team）。
图1 敏捷名称来自于英式足球
1.4 关于规模化敏捷框架
规模化敏捷（Scaled Agile）即在敏捷开发的基础上，专门考虑到了团队规模、系统复杂程度及项目规划要求而产生的理论。目前广泛应用的规模化敏捷开发方法论为Dean Leffingwell的基于大规模的敏捷框架（Scaled AgileFramework,"SAFe”）[5]。规模化敏捷框架（SAFe）适合大型团体的合作开发工作，从而提升团队协作效率，降低复杂度和风险。本文所讨论的敏捷方法论具体为规模化敏捷框架下的做法。
规模化敏捷框架从3个层面清晰定义了敏捷规模管理的框架。第一个层面是投资组合层(Portfolio)，主要负责定义投资策略，并制定方向驱动，转化为史诗(Epics)。第二个层面是项目集层面(Program)，由产品经理对需求进行排序，并将具体的策略转化成特性（Feature），设计出愿景与路线。第三个层面是由更具体的团队（Team）从特性（Feature）出发，拆分成若干用户故事（User Story），并确定验收标准。
SAFe将开发周期按照PI（Program Increment）为大单位，用来对一列敏捷发布火车（Release Train）的提交和发布时间进行总体规划。将PI分为多个迭代(Sprint)周期，每个Sprint周期通常为2-4周，用来进行具体的工作计划和实施。Sprint 的长度保持一致。前一个 Sprint 结束后，新的下一个 Sprint 紧接着立即开始。在具体的操作中，每个具体的敏捷团队（Scrum team）自己根据实际情况选择、合理排序用户故事。本文所探讨的做法即从更具体的第三个层面出发，研究技术文档部门在不直属于研发敏捷团队的情况下，如何以用户故事为切入点更好地与团队合作，及时撰写和更新用户文档，保证文档质量。
图2 从产品需求列表到产品增量
2 敏捷开发流程下的医疗器械软件用户文档
2.1 产品介绍
本文主要以Monaco这款软件产品为例来说明技术文档工程师是如何在敏捷环境下与开发团队协作共进、保证及时更新。Monaco是一款功能强大的放射治疗计划系统，支持目前所有放疗照射技术，如三维适形（3D），逆向调强（IMRT），旋转容积调强（VMAT）和SBRT等多种照射技术。除了传统的电子、光子计划，Monaco也支持质子及重离子放疗计划，是集多功能于一身的肿瘤放疗计划系统。Monaco 产品的目标用户是在医师指导下的有资格的人员。这些用户应熟知放射治疗计划约定（包括 IMRT），获得所在国家授权机构的认证，并持有所有相应的专业执照。Monaco系统用于为肿瘤患者制定治疗计划，并提供外照射处方放射治疗。Monaco系统为光子和电子治疗计划计算放疗剂量，并在屏幕上和硬拷贝中显示给定患者体内的二维或三维辐射剂量分布治疗计划的设置。
Monaco的文档目标用户即Monaco的使用者和产品维护者，文档随产品发布而发布，随产品更新而更新。技术文档部门负责的产品包括用户使用文档、发布说明、在线帮助文档、缺陷列表等。其中，在线帮助文档作为直接显示在产品用户界面上的文档作品，需要与代码同时入库、同时发布，这对文档工程师保证及时更新文档提出了时间层面上更紧密的要求。
2.2 具体实践
2.2.1以用户故事为驱动的文档撰写
软件开发的速度不能及时迎合用户需求变动频繁的问题一直是软件项目的痛点。所以正确的策略不是排斥变动, 而是尽量减少变动的成本[6]。敏捷针对软件研制过程中遇到的需求频繁变动、任务节点较紧的问题给出了很好的解决方法论。敏捷需要拥抱变化。通过对价值观的实践，Scrum是用于开发、交付和持续支持复杂产品的一个框架，是一个增量的、迭代的开发过程[7]。敏捷方法已经在众多实践中取得了巨大的成功。这告诉我们，敏捷是提高软件生产率不争的事实。然而事情过程本身不是敏捷的，但人可以敏捷，团队或者组织可以采取敏捷的方法论。如果只是做敏捷而不是敏捷地去做，就会导致敏捷方法应用的失败[8]。这就是医科达文档部门采取的思维模式。敏捷开发方法注重人与人之间的交流，强调以人为核心，与以往传统的讲究编制详细的计划和技术资料的文档驱动方法不同[9］。
尽管文档工程师不属于具体的敏捷开发团队成员，但技术文档工程师仍然可以参加每个团队的敏捷规划会议，在每个sprint里为开发团队即将开展的新功能建立文档专属用户故事(User Story)，以每个sprint里具体的文档用户故事为驱动，合理安排工作进度，以敏捷的步伐保证文档与开发工作保持统一的步调。
这样，对于每一个团队来说，在sprint结束的审查会议上都可以保证文档工程师与开发团队的节奏一致，齐头并进，从而确保文档工程师在规定的截稿日前以完满的形式交付用户文档。
图3 技术文档与开发团队的Sprint协作安排
在每次PI 规划会议上，敏捷团队们会明确制定此次PI要做的工作计划、整体的方向和承诺的产出。具体到每一个Sprint, 团队会根据特性（feature）拆分出具体的用户故事(User Story)，。根据特性的开发进度安排和人员可用资源预估，合理安排每个Sprint需要完成的用户故事，以达成每个PI完成具体特性（feature）的目标。
下表列出一些常规的PI会议的基本内容，以及文档部门相应的参与。
|
序号 |
PI会议 |
内容 |
文档工程师 |
|
1. |
情境与愿景会议 |
组织管理人员从当前公司业务现状出发，分享公司总计划的愿景，展示可以满足用户需求的方案。
|
文档工程师参加此会了解公司计划的愿景，了解工作的大方向。 |
|
2. |
敏捷团队规划会议 |
各敏捷团队根据需求方案起草PI计划，并识别当前工作风险和团队之间相互的依赖度。 |
文档工程师需参加敏捷团队规划会议，了解接下来即将开展的工作，并开展文档工作计划。 |
|
3. |
计划初版审核会议 |
在计划初版审核会议上，每个敏捷团队需要在固定的时间内介绍他们为此PI建立的计划、潜在的风险和依赖、负责人、产品管理、以及收到的一些反馈。 |
文档工程师参加计划初版审核会议了解组织内所有敏捷团队的初版计划，有助于为后续安排文档工作做好准备。 |
|
4. |
最终计划审核会议 |
在最终计划审核会议上，所有团队展示他们经审核修改最终定稿的PI计划内容，并听取意见。 |
文档工程师参加最终计划审核会议，了解组织内所有敏捷团队的初版计划，有助于为后续安排具体迭代文档工作做好准备。 |
表1 常见的PI会议与文档工程师的参与
技术文档工程师作为产品开发过程中的一员，需要及时更新文档，保证文档可以在被需要的时候按时发布。对于涉及到用户操作层面的新功能，医科达文档部门的做法是相关的Feature下必须建有专门的文档用户故事(User Story)，并根据开发进度和文档工程师可用资源预估，分配给相应的文档工程师，合理地排序到每个sprint的安排表单中去。
每个Sprint的会议流程包括Sprint 计划，每日站会，Sprint审核以及Sprint回顾会等（见表格1）。在每个Sprint结束时，敏捷开发团队在召开的Sprint 评审会议会上总结当前Sprint已完成的工作，总结工作经验和教训。这样，在每个sprint结束验收会议上，可用确保文档工程师的用户故事已经完结，相关的文档稿件已经处于撰写或完结状态。
假设根据团队A的PI计划，他们将在Monaco某页面上添加一个有关于DICOM数据导入的悬窗，工作计划于Sprint 1.1开始，并将于Sprint 1.2完成该功能的代码开发工作。文档工程师可以在Sprint 1.1和Sprint 1.2分别为该功能创建一个用户故事，用于跟踪工作的进度和变化，并及时完成用户文档的编写。
在Sprint 1.2回顾会议上，敏捷开发团队可以和文档工程师回顾该功能的最终完成状况，并验收相关用户文档。
下表列出一些常规的Sprint会议的基本内容，以及文档部门相应的参与。
|
序列 |
会议 |
会议内容 |
文档工作 |
|
1 |
Sprint规划会议 |
Sprint规划会议旨在规划当前Sprint工作。计划会议在每个迭代的第一天举行，目的是确立Sprint目标，将用户故事拆分成更小的任务（Task），估算本次迭代工作项。 |
参加规划会可以使得文档工程师了解即将开启的工作，并建立相对应的用户故事与敏捷团队挂钩。 |
|
2 |
每日站会 |
每日站会旨在审查每日工作进展以及遇到的问题，并为了实现Sprint目标而做出及时的调整。每日站会召开的时间为每天早上开工时，通常在固定的时间和地点举行，时长一般控制为15分钟以内，组内成员轮流发言。 |
文档工程师可视情况参加每日站会，了解团队最新进展，与团队保持及时沟通，合理安排文档工作进度。 |
|
3. |
Sprint审核会议 |
Sprint审核会上团队一起审核该Sprint完成的工作，并审核质量，确保工作方向是朝着设定的目标前进。团队向团队成员和被邀请的参会人员展示本次迭代取得的成果和演示新功能。如果在此期间对功能有了新的想法，团队可将其添加到新产品需求列表以做记录。 |
文档工程师需要参加Sprint审核会，通过观看团队的演示，确保文档内容的准确性、有用性。 |
|
4 |
Sprint回顾会议 |
Sprint回顾会议旨在规划提升质量和工作效率。主要是团队针对问题进行反思，对于发现需要改进的地方，需要在会上提出建议。在回顾期间，团队将会讨论：
|
文档工程师可根据工作实际安排，合理按需参加Sprint回顾会议。 |
|
5 |
Sprint优化会议 |
Sprint优化会议关注下一个Sprint即将着手的用户故事，团队一起讨论具体的需求，形成对即将开始的工作初始的理解。 |
文档工程师可根据工作实际安排，合理按需参加优化会议，了解即将进行的工作。 |
|
6 |
知识分享会议 |
团队在知识分享会议上展示他们在此Sprint的工作中学到的技术和新想法，进行技术分享和交流。 |
文档工程师可根据工作实际安排，合理按需参加知识分享会议。 |
表2 常见的Sprint会议与文档工程师的参与
2.2.2 针对共享服务---以GIVE&GET为驱动的文档审核修改
共享服务（Shared Services）是指一些特定的专业人员，他们致力于实现整个组织为敏捷发布火车制定的成功目标。但共享服务通常不能完全投入于仅仅某一个特定的敏捷开发团队，而是服务于组织内的多个研发团队。技术文档工程师正属于共享服务的一员。除此之外，与传统的软件开发不同，医疗器械软件的开发涉及到大量安全、法规、验证等专业人员的参与，这些也都属于共享服务的范畴。作为公司的员工，他们不单单为公司的某一个软件产品服务，而是公司开发的软件都必须经过安全、法规、验证等共享服务团队的审查和修改，才可以进入到发布环节。常见的具有特定技能的共享服务人员有:
|
常见的共享服务人员 |
|
|
敏捷教练 |
基础设施管理员 |
|
应用程序管理员 |
系统质量保证员 |
|
法律法规专员 |
信息架构师 |
|
数据建模，数据工程，数据库维护员 |
技术文档工程师 |
|
IT服务管理和部署工程师 |
数据安全专员 |
表3 常见的共享服务人员
为了保证文档产品的撰写和发布能够顺利进行，文档工程师需要在规划工作时与共享服务的人员进行用户故事层面上的捆绑，从而确保可以及时得到最新的反馈结果。
在敏捷中，有着给出（GIVE）和获取（GET）这个概念。敏捷开发成员可以建立一对以给出和获取为主题的用户故事，从而确立起与共享服务成员的协作关系，保证提前预定到对方的工作时间和承诺。给出或获取是敏捷中用于管理对外部团队依赖的一种方式。团队成员可以建一个以获取为标题的用户故事，意在从另一个团队或供应商得到某种信息或服务，也可以建一个以给出为标题的用户故事，旨在为另一个团队或供应商提供某种信息或服务[10]。
需要注意的是，作为团队成员，不可以为自己内部的团队成员建立给出或获取用户故事，因为团队的产品专员和其他成员可以控制自己的工作进度以及相关的影响。给出或获取必须建给团队外部的成员，是用于确定工作依赖关系的一种方式。
假设现在需要在Monaco页面上增设一条预警信息，以提示用户接下来的操作可能会有临床方面的风险，作为文档工程师，需要确定软件页面上的预警信息措辞是否正确，并将此条更新加入相关的用户文档内。由于临床风险预警信息涉及到了法规和安全的领域，文档工程师需要和法规以及安全工程师进行沟通，以确保在文档发布前更新的内容得到了他们的验证许可。
如图所示，文档工程师将会在敏捷计划工具中建一个以“给出“为主题的用户故事预定法规工程师的时间，以将相对应的编辑好的用户文档发给对方，标注出修改的部门。作为回应，法规工程师将建一个以“获取”为主题的用户故事还给文档工程师，确保文档工程师将按时得到对此文档的审核修改意见。同理，对于安全工程师的流程也是如此。同理类推可创建更多的给出和获取给涉及到的相关共享服务人员
图4 以给出和获取为驱动的共享服务
技术文档部门通过建立给出和获取，确立起了与安全、法规、验证等共享服务的依赖关系，提前预定的对方的时间。通过在相应的sprint下建立一个给验证团队的给出，再建立一个验证团队给回文档部门反馈的获取，并分配给具体的人员，这样就可以实现文档在合适的时间获得充足的反馈，不会出现临时赶工或修改的现象。在实践中，文档部门通过这种方式获得了及时的、充足的反馈，与其他共享服务团队构成了良好的合作。
3.成效反馈
不同于传统瀑布式的开发模式，文档工程师不必再等待团队的功能开发和测试等工作就绪，再开始进行用户文档的撰写和修改。敏捷框架下的文档撰写是与团队的功能开发工作同步进行、同步修改，这样确保了文档工程师与团队的实时的融入与合作，可以很好地避免重复或无效的沟通和返工。
基于敏捷方法的特点，以及医疗器械软件开发过程中需求多，法律法规、安全验证角色参与度高的特点，改进了基于敏捷开发过程中技术文档部门协作的方法，强调了技术文档的撰写和修改应该基本与团队开发进度保持一致，并需要及时与共享服务团队沟通协作。从项目开发的角度出发，此方法的优势如下：
- 降低返工的可能性，减少了学习的成本。由于在开发过程中文档工程师与团队保持实时的更进，因此工作的最新变更都可以及时地反映在文档产品中，这避免了文档的更新不及时，或因为文档工程师对新功能的理解错误而出现返工的现象，文档工程师与团队可一起学习，共同成长，确保持续跟进、持续交付的实现。
- 合理安排工作量，确保工作效率的提升，避免赶工。通过每个Sprint确定工作量，可以提高文档工程师的写作质量和交付的及时性，避免因突发情况文档不能及时跟进而出现赶工的情况。
4. 经验启示
随着技术传播行业的不断进步与发展，提供清晰、准确、及时发布的技术文档是成功发布产品要素中不可忽视的一部分。尤其是对于快速发展的医疗器械软件行业来说，技术文档工程师要有意识地融入开发团队，采取积极的方式方法与开发团队和共享服务团队保持畅通的沟通交流，而不是消极地等待最终产品功能的完结阶段才开始进行文档的撰写工作。相比传统的“瀑布式”开发方法，敏捷方法论以人为本，关注人在整个软件开发中的作用。这对于技术传播工作者来说极为重要。作为文档开发者，我们需要做信息的及时接受和转化，融入到敏捷的大环境中，实现快速、有效、高质量的技术文档发布。
目前，国内不少中小企业的技术文档部门仍处于摸索的发展中阶段，对于技术文档工程师与团队协作的方式仍没有形成相对成熟的模式。本文基于敏捷思想的理论基础上总结出技术文档部门依据敏捷的方法论原理与公司内产品开发团队以及共享服务团队保持有效、密切沟通和合作的方法，这给国内中小企业在未来推动改进技术文档部门与各部门协作方式提供了一些可借鉴的思路。
参考文献
[1] Schwaber K, Beedle M. Agile Software Development with Scrum[M]. [s.I.]: Prentice Hall, 2001.
[2] 赵俊, 石春. 敏捷思想在软件开发中的应用与实践研究[J]. 电脑知识与技术, 2020, 16(9):98.
[3] Manifesto for Agile Software Development[EB/OL].2001[2022]. https:/agilemanifesto.org/.
[4］王哲. Android 敏捷开发指南[J]. 程序员, 2012(21).
[5] 张天龙, 路文婷, 任志强. 大型国企知识管理的规模化敏捷开发研究——以浙江电力专业案例库开发为例-[J]. 价值工程, 2019, 38(03):22.
[6] Highsmith J, Cockburn A. Agile software development: the business of innovation [J]. Computer, 2001, 34(9):120-121.
[7] 高俊. SCRUM 敏捷开发在移动应用开发中的实践[J]. 信息技术与信息化, 2019, 12(025):80.
[8] Pollice G. 敏捷起源以及敏捷创始人的传记[EB/OL]. 2009[2022]. http://www.scrumcn.com/agiledev/html/?169.html.
[9] 马睿．轻量级的软件开发新模式—敏捷开发［J］．通讯世界，2017(1):259－260．
[10] JOE VALLONE. You can depend on me – Planning and Managing Dependencies and Risks in Agile[EB/OL]. 2013[2022]. https://agilebizconnect.com/2013/10/14/you-can-depend-on-me-planning-and-managing-dependencies-and-risks-in-agile/.
基于规模化敏捷开发流程下的技术文档编写与内容管理
以医疗器械软件用户文档为例
沈晚双 杨悦明 张雅瑾
医科达（上海）科技有限公司
