架构师职位与软件文档的思考
作者：sagahu@163.com，2013-04-11，太原。
关键词：架构师, 软件文档
一、前言
笔者最近入职一家软件公司做架构师，发生了一些适应期的问题，这里写出来，与大家共勉。
本人从事行业多年了，感受到了许可共性的需求及对应解决方法，迫切地需要分析、总结，并且规划、设计并实现为成品系统或者子系统，最低也是模块重用或者模版套用。而这家公司也可以算是本地业内首次招聘架构师，呵呵，看来有共同的感受，与公司领导接触也是如此，就入职了。
第一天部门领导说，做个方案，实现通用的权限管理，等等。笔者以前实现过基于角色-功能的权限许可，也静态代码实现过依赖组织结构的资源许可（当然仅仅依赖于组织结构的上下级），有实践感受，欣然开工了。
新人，时间也太短，入手后发现了通用的资源权限是个关键难点不好设计，就来不及编撰完整文档了，忙着画了些主要的类图、关系图，计划讲解主要设计思路。三天后第一次研讨（有些评审性质），与会两种人：行业解决方案部（应该是技术性的业务人员）、研发部。我并没有做到提前在会下的沟通！
行业解决方案部：我们需要看到你说明能实现什么，解决什么问题，怎么实现？
研发部：看不懂你画的UML图，你用数据表更好说明问题！
这次会议到下班时结束，没有结果，没得到认可。这时候，我还没搞清楚原因。
我思考是不是因为我关键问题没把算法理出来，写的文档不完整，讲解表达也不够清晰、条理？然后在公司又写了2天，清明节放假3天在家里加班，搞了一套基于SOA后台集中认证与提交时许可验证、配置条件式资源范围定义用于向角色分配的通用权限管理子系统模型，初步形成了文件，包含子系统界面，中间SOA后台，后端数据库，以及相应验证案例。当然，这样的东西在一周时间不可能把所有细节都理出来，除非盗用现成的。而且这样的产品有实力的公司最少需要半年来实现，国家级公司更是严慎、完善到规划至少一年时间。
再次开会研讨与评审，还是不能得到全面认可。但是我终于反应过来了，包含2点：（1）本公司研发部门首先要向行业解决方案部“出方案”。行业部人员向研发部口口声声要的“需求”，其实是他们习惯了的解决方案类的文档，不是专业的需求分析说明书，所以“需要看到你说明能实现什么，解决什么问题，怎么实现”。而我真把自己当成总结提炼共性需求的架构师去画UML图，所以难于沟通到一个共同点上。（2）也许该公司曾经有想法搞个高级的通用模型/产品，但是还是针对眼前火烧眉毛的需要，不能像我上面方案那样太高级而需要太长时间。所以让我简化，别考虑字段级权限，别考虑通用的资源范围定义与分配，只要实现对组织结构依赖的就可以了。
接下来，我按照解决方案的规范，分析实际需求，简化要实现的目标，用2天多时间编写出来《简单通用权限管理模型技术解决方案》，中间与部门领导研讨几次，自感这个文件可以定下来了，但是相关人员没时间审阅。我就继续推进设计吧。
呵呵，新人适应不容易；公司新岗位大家也不太理解。下面接下来谈谈个人对软件文档与几个常见职位的理解。
二、项目阶段与软件文档分析
软件项目前期工作中常常会有这些文档：行业解决方案、需求分析说明书、概要设计说明书、详细设计说明书，可能还有可行性论证等等。这些文档显然各有区别。
当软件公司人员接触客户时，客户首先会向前者索要解决方案，或者是行业解决方案，要求项目/任务目标（产品）描述：（1）实现那些功能与流程，（2）可以解决那些问题，（3）达到什么样的效果。
接下来，可能双方确立解决方案的可行性；当然也可能认为简单，而直接跳过可行性论证阶段。
然后，客户可能故作专业的向软件公司索要需求分析。需求分析说明书，又叫产品规格描述，它是用来描述，也是限定产品的外观指标（要实现的功能与流程，操作说明，等等），及可能的性能指标、外扩接口协议、部署配置要求等等。总之，需求分析阶段是要确定软件研发要实现的目标，“说明要实现什么”；至于怎么实现，则是设计阶段与编码阶段的任务。
设计阶段“定义如何实现”。设计文档：表达系统模型与算法的模块划分、模块部署/配置、单元规格及接口规范，以及算法（有复杂度的部分）描述。设计阶段又细分概要设计与详细设计两个阶段：概要设计文档需要从概念层次来表达以上内容；详细设计文档则是侧重以上内容的技术规格以及确定算法，要求准确性及标准性。
编码阶段则是具体的实现。
这样看来，解决方案与需求分析说明书应该有着以下区别：解决方案更像是绘制美好的蓝图，更加趋向市场人员的领域；而后者从理论上来说，需要在“实现什么”这个目标上，可以同时指导客户与软件研发人员，比解决方案要专业技术性强的多。实践中几乎找不到客户人员与软件技术人员来较长时期的研究UML图，所以实践中更是侧重指导研发人员。实践中，在解决方案之后客户要求需求分析时，真有不少软件公司仍然不让技术人员介入，还是让市场人员把解决方案改改，就当成需求分析说明书，然后非常协调、沟通能力强的把客户给解决掉了。当项目简单时，软件研发人员倾听市场人员转达，凭经验基本上能把项目完成。但是项目复杂时，研发人员的不到市场人员的需求分析说明书，自己也不可能凭空生产这东西，大多数时候会成为“弱势人群”。
三、什么是架构师
架构师本身是设计人员，但是与设计人员最大的区别在于，前者必须更加注重：（1）通用，（2）重用。这依赖于（1）丰富的行业实践经验，（2）广泛的技术认识。当设计人员有着较多的行业实践体验时，就会比较强烈感受到需要提炼、总结需求与解决方法的共性，而追求产品通用性与重用。架构师必须是技术高手，但是首先侧重技术广度，其次才是技术深度；也可以说是首先要求对技术如何恰当使用的理解，其次才是技术的具体使用。
架构师对于具体项目或者模块任务，主要是关注建模与算法，然后予以分割，为分配实现任务作准备。模型、算法、分割任务一般都应该表达为系列化的文档，还常常以讲解的形式与相关人员沟通，来逐步达成共识。模型与算法在需求分析阶段也需要，所以会使用UML、OOP、E-R等等专业图形。架构师还常常习惯性地，把实际项目的需求部分，甚至整体向共性问题的层次上升，对于设计模型也追求“优雅”，而把工期拉长，呵呵。
架构师编写需求分析，也会常常侧重对研发的指导，就是说文档的技术性强，而使得客户感到抽象与枯燥，这也是个特点！
在一些公司的职位设置里，可能让架构师偏向管理工作。但是要注意，架构师是协助项目经理，而不是代替项目经理的整体或者一部分。
把软件团队几个高层职位做个比较，可以这么概括：普通设计师要达到“能使用”的要求，而系统架构师是“重用与通用”，技术架构师是“足够用”，技术专家“会的多”，领域专家对特定领域“精深”，项目经理是“协调、管理”，业务专家“对业务精通”而不论技术。
总之，架构师的基本职责是建模、算法、分割，并且提高层次来追求通用与重用。