想探讨两个关于设计文档问题

最近一直感到无助，发生太多太多令人无法理解的事。今天在写道歉信给Manager的时候，心都有滴血的感觉，几滴眼泪也不争气的下来了。我知道这次确实是我犯了错误，但是个中缘由又有谁能够完全分的清，又了解我现在的感受呢。那份道歉信其实是写给Manager的Manager看的，但有些狠话还是最终没有写上去，因为我们一心只求息事宁人，只是希望目前阶段做出足够优秀的产品，所以我们总是遭受委屈的那一方。

抛开这些不说，其实自身跟Manager某些观念还是没能达成一致，也经常“顶撞”到Manager，也许这也在他眼里留下了越来越差的印象。Sorry，但，有意见不说不是属于我的Style。

这些问题也困扰了我很久很久，对于语言表达能力匮乏的我，如实地描述我内心想法的已是困难，但又很想能够得到过人来的指点，因此就有了如下的文字，希望能得到有心人的指点：

焦点一：Design必须细化到足够的detail

焦点二：必须严格按照Design Document实施代码

 

两个问题看似好像没什么歧义，你问我同不同意它们， 我肯定回答同意， 但是请听我说完。

我只是同意但不完全同意。

首先关于第一个，我的concern在于，细化到何种程度，我完全同意任何Coding前都应该有design先行，都应该有所构思，但是都应该写Design文档吗？Design文档必须要覆盖到“所有”细节吗？举个例子，Design文档里已经详细地描述了CreateCommand的类图，交互图和序列图，描述其如何与外部类交互，描述了其单次的一整个操作流程。同样类似的一个CopyCommand，我也必须细化到CreatCommand的程度吗？

我觉得如果这两个command的实现的机制是一样的就完全可以省略或只需粗略的勾勒下CopyCommand， 大可不必凡是都每次细化到不能细化为止。除非描述的是两个完全不同的东西，有着不同的实现机制。

关于CopyCommand内部的逻辑，如果内部实现方式只需简单地调用DataModel的方法，我也需要在类图里面详细再体现吗？

我的观点依然是否定的，除非CopyCommand的实现逻辑非常复杂我觉得才有必要用序列图或其他的手段去描述说Step 1…，step2…

So，我的关于Design文档的总体观点就是，Design文档不是全部，这个只是用来交流的工具，描述你是怎么解决问题，尽量但不等于全部问题的solution都要体现在文档里面。任何一个reviewer对某个问题是怎么得到解决的有任何疑问都可以探讨，再细化, 难道不是吗。 如何一个问题用一句话描述，大家都应该能懂的时候，为什么一定要细化到具体的1，2，3… 

有人反驳说，万一大家看了不懂一句话的描述，如何如何。那么这个理由能成为我一开始就必须详细描述1，2，3…的理由吗？我觉得不能，我们说八九不离十，如果你觉得有八九分的时候就可以不写，何必一定要达到十呢，完美只是浮云。 当然如果你的信心指数只有五六，那最好还是写具体点。如有八九分，我的做法就是不写，review过程中对其有任何concern，我们可以再解释并更新到文档。

附带一个问题，Design文档必须要让所有人看了都明白才算合格吗？

我的观点依然是没有这个必要，Design文档的最小需求是让所有实现者参与者能够看的明白，并且使他们认可它真的能解决现有问题。考虑到我们的经验尚浅，自然应该被Architect review，也必须能让Architect看得懂。至于这个Manager那个Manager，只需让其看上去不会感觉太差就OK了，不应该强求一定要能使能令他们全看的懂。

上面的这个问题依然是关于度的问题，满足一个不熟悉架构，不太了解关心技术问题的人的胃口太累太难了。我们说演讲者做演讲时首先要了解听众的背景。Design文档也应该有其特定的目标群，而非所有人。So， 能够让所有人都一看都懂自然最好，但不应强求。

在这个敏捷开发大行其道的今天，Design到所有细节真的能站得住脚，有必要吗？

写Design文档的人真的能神通广大，看看，想想，就能涵盖所有的细枝末节吗？

 

其次关于第二个，我的理解是必须，但我今天就是栽在了这个问题上。因为在“必须”之外，我依然有些小小的自我观点，Design文档必须要有必要的信息去体现的作者的意图，写的人应该尽量多次推敲，一份粗略地不能再粗略的Design丢出来的，为什么就能够被大家接受呢？你可以说我也看过没有发表意见。 我承认我错了，我应该站出来问个明白，但我当时还在感叹那个Design。今天我没有完全按照Design来，我确实应该被批，但您能否稍微思考下谁是始作俑者。

另一方面，如果Design文档事事详尽，谁能保证Design文档上的就都是对的，跟实际没有出入呢？这个时候我们还有必要死按照文档上的做吗？当然你可以说先沟通，再实施，我同意但仅限于大的issue。所有的细枝末节都应该这样去做吗？考虑过沟通成本吗？

 

太粗略的Design文档是不应该，事事必详尽的Design就一定是我们追求的吗？