/ 杂想

多视角文档模型

重要的不是你拥有什么,而是你如何去看

起因

假如需要写一个Web项目的详细设计,说明前后端各接口的作用以及实现策略,那么很有可能是这么一个结构:

1 功能A
    1.1 URL接口
    1.2 传递参数
        1.2.1 参数1
        1.2.2 参数2
        1.2.3 参数3
    1.3 相关类
    1.4 具体实现策略
    1.5 补充及注意事项
2 功能B
    2.1 URL接口
    2.2 传递参数
        2.2.1 参数1
        2.2.2 参数2
    2.3 相关类
    2.4 具体实现策略
    2.5 补充及注意事项

注意图中每一大点的1、2、5小点是前端人员所关心的,而类似“相关类”和“具体实现策略”等内容则是服务器端开发人员的职责范围,当然其中也有“传递参数”、“补充及注意事项”等栏目是双方都需要给予一定的关注的。

那么,当这样一份文档拿到前端人员的手中,面对着其上成百上千行的“具体实现策略”,茫茫字海之中无法寻找到自己需要的接口的URL地址,会是一种什么样的悲剧呢?

为了解决这个问题,可能有下面几种解决方案:

  • 不管死活所有人看一份文档,请自己高亮你需要看到的内容。很显然这么做对于广大的开发人员都是一种痛苦的折磨。
  • 将文档一分为二,分为前端人员版本和服务器端开发人员版本。但是两个文档又存在通用的部分,使用复制/粘贴必然为将来的版本维护带来麻烦。
  • 每个部分有明确的标题,使用文档地图,阅读者通过文档地图来定位到需要的部分。这是一个比较通用的解决方案,但只能有若干级的结构,对于文字中某些注释等无法进行支持。
  • 本次的主题:多视角文档模型,就是为了解决上文提到的问题而诞生的。

概念

再次回顾上文提到的问题,事实上需要的一个解决方案应当有以下的特征:

  • 文档自始至终只有一份且不能拆分。
  • 不同角色人员看到的内容不同。

因此,多视角文档模型就是一种“可以由不同角色通过不同角度观察到不同内容的文档模型”。

为了更加清晰地展示这个问题,请试想一个简单的图表页面,通过选择右方的复选框可以控制不同的折线是否显示。事实上这就是从多个角度看一样事物的经典例子,而“多角度文档模型”正是将这种思想运用到文档之上。

在多角度文档模型中,团队自始至终维护同一份文档,只是文档自身将分为若干个“片段”,相关的“片段”将形成“片段组”,不同的人将看到不同的“片段组”。

在这种模式下,首先文档的维护问题迎刃而解,同时也更有利于源码管理系统的结合,保证所有开发人员得到的都是最新版的相同的文档,再通过不同的角度去查看文档,寻找到自己想要的内容。

术语

要从概念上理清整个多角度文档模型,就不得不提出一些术语,这些也是整个文档模型的最重要组成部分:

  • 文档(document):最顶层的文档自身,在整个模型中永远只有一份,是一个不可分割的整体。
  • 片段(section):文档中连续并有关联的内容的集合,作为文档视角切分的最基本单元。
  • 片段组(section group):同类型的、相关联的片段组成的更大的整体,一个片段组通常对应一个或多个视角。
  • 角色(role):文档阅读人员的身份标识,一个阅读者可以有一个或多个角色。
  • 视角(perspective):查看文档的具体角度,从一个视角查看文档,可以看到不同的片段组组合而成的唯一的伪文档(对使用这个视角的阅读者而言,这就是一个文档,但从数据上而言,只是文档的一部分)。
  • 阅读者(reader):最终端的文档的阅读者,可以有一个或多个角色。

实现?

该文档模型现在还没有一个真正的实现,就逻辑而言,其实现过程应当如下:

  1. 获取无模型的普通文档。
  2. 定义文档拥有的片段组。
  3. 将文档进行切分,提取片段,将每个片段分配不一个或多个片段组中。
  4. 切分文档的视角,定义每个视角可以查看的片段组集合。
  5. 定义阅读者的角色,确定每个角色可以使用的视角。
  6. 输出最终的文档模型。

发展?

最初设计多视角文档模型,其目的在于更好地管理项目中的不同文档,并且将有重复内容的多个文档合理地归并为一个整体,同时不妨碍开发人员的阅读。

更进一步地设想,除了项目文档,其实有很多东西是可以使用这样的模型的:

  • 对小说进行建模,在快餐文化泛滥的今天,喜欢打斗场面的可以只看各小说中的打斗场面,喜欢浪漫爱情的可以只看星空明月……
  • 对论文进行建模,可以选择先看结论,可以选择先看论证过程……
  • 对视频进行建模,可以完美地跳过OP、ED、过场……
  • 对游戏进行建模,GAL类可以跳过各种平凡的生活场景,RPG可以跳过好多走路……

在此仅仅是一个概念性的产品,一切都有待发掘。