多视角文档模型

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

起因

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

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

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

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

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

概念

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

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

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

为了更加清晰地展示这个问题，请看下面的演示

这是一个简单的图标页面，通过选择右方的复选框可以控制不同的折线是否显示。事实上这就是从多个角度看一样事物的经典例子，而“多角度文档模型”正是将这种思想运用到文档之上。

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

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

术语

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

文档（document）

最顶层的文档自身，在整个模型中永远只有一份，是一个不可分割的整体。

片段（section）

文档中连续并有关联的内容的集合，作为文档视角切分的最基本单元。

片段组（section group)

同类型的、相关联的片段组成的更大的整体，一个片段组通常对应一个或多个视角。

角色（role）

文档阅读人员的身份标识，一个阅读者可以有一个或多个角色。

视角（perspective）

查看文档的具体角度，从一个视角查看文档，可以看到不同的片段组组合而成的唯一的伪文档（对使用这个视角的阅读者而言，这就是一个文档，但从数据上而言，只是文档的一部分）。

阅读者（reader）

最终端的文档的阅读者，可以有一个或多个角色

实现？

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

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

发展？

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

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

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

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

 

本文永久地址：http://www.otakustay.com/multi-perspective-document-intro/