1 为什么要写技术文档
回顾软件开发历史,我们可以将其分为程序设计时代、程序系统时代和软件工程时代三大历史阶段。
在程序设计时代(1946-1956),软件开发主要依赖于个人编程技巧,技术文档只要存在个人开发者的大脑即可,因为没有沟通和协作需要,编写技术文档也不具有紧迫性。
在程序系统时代(1956-1968),计算机性能显著提升,应用范围和规模逐步扩大,以至于依靠个人无法完成软件的开发,所以出现了团队合作。在早期团队合作过程中,开发者仍然保持了早期各自为战的开发习惯,即使出现了一些方法论雏形,也无法从根本上控制沟通和协作的巨大成本,软件危机就此出现。1968年国际学术会议提出了软件危机和软件工程的概念:
软件危机定义是落后的软件生产方式无法满足迅速增长的计算机软件需求,从而导致开发与维护过程中出现一系列严重问题的现象。软件工程定义是建立并使用完善的工程化原则,以较经济的手段获得能在实际机器上有效运行的可靠软件的一系列方法
从此软件开发进入工程化阶段,也应运而生了大量开发方法论和开发模型。其中标准和完善的文档是软件工程重要组成部分,可以很大程度上减少沟通和协作成本,而开发文档又是技术文档重要组成部分。
2 开发文档要体现什么
软件系统生命周期包括定义、开发、运维、消亡这四大阶段。定义阶段包括定义问题、可行性研究和需求分析。开发阶段包括概要设计、详细设计、代码编写和测试阶段。运维阶段包括更正性维护、适应性维护、预防性维护和完善性维护。消亡阶段包括系统报废、优雅下线和遗留系统。
生命周期每个阶段固然有各自的重要性,但是开发者更应该关注定义阶段与开发阶段。定义阶段需要解决为什么开发(why)、需求是什么(what)两个问题,开发阶段需要解决怎么设计,怎么编码,怎么测试(how)三个问题。
开发文档是否需要体现定义和开发的所有子阶段?我认为也无必要。问题定义和可行性研究主要由产品经理负责,测试阶段主要由测试人员负责,开发者可以关注但不是必须体现在开发文档。我认为开发文档必须要体现需求分析、概要设计、详细设计、代码编写四个子阶段。
3 七大维度
我认为一份完整开发文档应该至少具有七大维度,每个维度描述系统的一个侧面,组合在一起最终描绘出整个系统,这些维度分别是:
四色分领域
用例看功能
流程三剑客
领域与数据
纵横做设计
分层看架构
接口看对接
本文我们分析一个足球运动员信息管理系统,这个系统大家可能也没有做过,我们一起分析这个系统。需要说明本文着重介绍方法论的落地,业务细节难以面面俱到。
3.1 四色分领域
3.1.1 流程梳理
首先梳理业务流程,这里有两个问题需要考虑,第一个问题是从什么视角去梳理?因为不同的人看到的流程是不一样的。答案是取决于系统需要解决什么问题,因为我们要管理运动员从转会到上场比赛整条链路信息,所以从运动员视角出发是一个合适的选择。
第二个问题是对业务不熟悉怎么办?因为我们不是体育和运动专家,并不清楚整条链路的业务细节。答案是梳理流程时一定要有业务专家在场,因为没有真实业务细节,无法领域驱动设计。同理在互联网梳理复杂业务流程时,一定要有对相关业务熟悉的产品经理或者运营一起参与。
假设足球业务专家梳理出了业务流程,运动员提出转会,协商一致后到新俱乐部体检,体检通过就进行签约。进入新俱乐部后进行训练,训练指标达标后上场比赛,赛后参加新闻发布会。当然实际流程会复杂很多,本文还是着重讲解方法论。
3.1.2 四色建模
(1) 时标对象
四色建模第一种颜色是红色,表示时标对象。时标对象是四色建模最重要的对象,可以理解为核心业务单据。在业务进行过程中一定要对关键业务留下单据,通过这些单据可以追溯出整个业务流程。
时标对象具有两个特点:第一是事实不可变性,记录了过去某个时间点或时间段内发生的事实。第二是责任可追溯性,记录了管理者关注的信息。现在我们分析本系统时标对象有哪些,需要留下哪些核心业务单据。
转会对应转会单据,体检对应体检单据,签合同对应合同单据,训练对应训练指标单据,比赛对应比赛指标单据,新闻发布会对应采访单据。根据分析绘制如下时标对象:
(2) 参与方、地、物
这三类对象在四色建模中用绿色表示,我们以电商场景为例进行说明。用户支付购买商家的商品时,用户和商家是参与方。物流系统发货时配送单据需要有配送地址对象,地址对象就是地。订单需要商品对象,物流配送需要有货品,商品和货品就是物。
我们分析本例可以知道参与方包含总经理、队医、教练、球迷、记者,地包含训练地址、比赛地址、采访地址,物包含签名球衣和签名足球:
(3) 角色对象
在四色建模中用黄色表示,这类对象表示参与方、地、物以什么角色参与到业务流程:
(4) 描述对象
我们可以为对象增加相关描述信息,在四色建模中用蓝色表示: