虽然一直在读书群里混，按师父的要求每周写一篇文章，不过发现自己总是有点不误正业，说是写读书笔记，很多时候写的还是一些自己的想法。不一定对，但是写的过程实际上也是对思路的一种整理。
本周反思一下项目文档的事。
师父教导我们说面面俱到的文档不如能够跑的系统，加上系统真正运行的总是代码，而不是文档，早在当年开发的时候就不太喜欢写文档，但是从最近的一些事情上反思，在某些场景上文档还是很重要的。
场景一，需求文档：现在在项目当中需求文档的主要作用有几个：一是开发的依据，虽然开发听过需求，但是总是只能听个基本逻辑，细节部分在开发过程中最重要的参照物还是Story文档；二是Bug的依据，QA和开发同学一句Story的内容来确定一个问题究竟是Bug还是新的需求；三是对细节系求的追溯，在年久失修以后，细节逻辑没有人能想起来的时候，翻翻1年以前的Story文档来check。总的来看，这三个作用中最重要和不能取代的还是第一个作用。从这个角度看，Story文档中最终要的部分还是【Solution】。
对我们来说Solution其实没有固定的格式写法和特别的要求，但是却有一个最重要的原则，叫“言简意赅”。
言简意赅有点太虚，那么具化一点到Solution中就是要求写到三点：
1. 在哪里改：通常的写法是在XX功能页面上的XX处
2. 怎么改：通常的写法是把 XX逻辑改成XX逻辑。再具体一点，XX逻辑的写法通常建议为；如果XXX，那么XXX；否则XXX。这个看上去和写代码有点像，其实却是是这样，写得和伪代码越像，和开发同学们的共鸣不就越多吗。
3. 再补点什么：实际上有前面两点就挺OK了，但是对于一些复杂的Story，可以再补点图来帮助说明问题。
写清楚来上面的2+1点后基本上就意赅了。然后就此打住，至少在Soluton中不要再写其他内容了，是为言简。
最后，随便举挑两个Story的例子看看。
Case 1：
1. 在哪里改：写得还可以更清楚一些，建议补充进入的步骤，“如在订单查询功能的结果集中选择回单预览，在回单文件预览窗口中.....”
2. 怎么改：写得还是挺清楚的，基本上是：增加XXX，XXXX，如果XXX，那么XXX的句式，一看就和开发同学在一个频道上。
3. 补点图：也有了，挺清晰。
Case 2：
1. 在哪里改：看上去是清楚的，系统后台自动触发....... (不过这句话是我后补的...)
2. 怎么改：这里看上去有一些问题：根据逻辑处理数据，那么具体的逻辑是什么呢？ 根据我的猜测可能是基于系统中的一个下载报表然后结合3中的修改而成。那么就建议把这句话写出来：内容基于目前系统的预约查询下载，在此基础上进行样式修改，a,b,c,d....
3. 补点图：这个比较全，不过补点图始终是第二点怎么改的补充，改动点在怎么改中都应该体现。
此外，这里面还有一句不属于Solution的话："ps:客户对这个非常.......", 虽然我能明白这句话的目的，但还是建议写到Background中，而不是Solution中。
反思的第一部分就这样吧，其实可以说很久....
