研发小论之编码和文档视角

最近半年写的文档多一些,而前几年的工作主要是写代码和文档,从出发视角、受众范围等有些不一样,仅以自己的实际工作经历进行一点点思考,以供大家赏析: 1 出发视角: 1.1 文档视角 交流和沟通用,即是给人看的,所以主观上说视角较宽,形式可以为Word、PPT、Excel等,你不用受制于if-else逻辑思路,可天马行空的思考和发散。 重要:需要先做大纲和文档的规划,我说的不是写小说、散文,是指的计算机软件相关的规范、设计、计划等文档。 1.2 代码视角 给机器用,对编程很懂的人,看到你的东西就能理解思路和目标,但总体来说写代码思路比较受限,必须了解一门语言的特性,并把你要的业务转换为你理解的东西,再用代码实现出来,业务术语用英文单词或者简写写出来。 同时,由于大部分写代码没有经过严格的训练,代码质量参差不齐,如变量的命名有的人竟然非常乐于x,y,aa,bb,cc等单词,导致阅读的人痛不欲生。 2 受众范围 2.1 文档范围: 人员较多: 至少超过你自己,一般是小组内部,产品组内; 少数的是组间、产品组间; 极少的可在公司之间传播; 可通过邮件、SVN、版本号来管理。一般需要评审而定稿。 因为使用的人较多,故“众口难调”,考虑的东西也往往较宽。 2.2 代码范围: 影响力非常弱。以我自己的经历看,我写的90%的代码是给机器写的,偶尔才会自己回头看,而其他人看的概率非常低; 一是因为SVN源码管控权限,另外一个是因为看代码的意义不明确。往往用心去看别人写代码的人很少,但是一旦有这种习惯,则写代码的个人能力提升非常快。我所指的不是抄袭,是编程习惯的学习、编程思想。 以上就研发过程中的文档和视角简单说了一下。 一般来说,在我所经历的公司,学代码的程序员群体,写文档的非常少,或者仅有极个别会去写、填写规范模板规范,一般通过补的办法达到不扣分。 写文档的需求、业务人员,极少有机会动代码。 早些年,年少太轻狂,看古装剧太多了,把写文档誉为文臣,把写代码的誉为武将; “鬼子是用真刀真枪打倒的,不是写2~3个狗屁文档能消灭的”。觉的写文档没有啥子用,我代码都写不过过来,还要求写文档。“并把文档工作贬为繁文缛节,不肯屈伸事之。“ 而后过了几年,随着日渐增多的积累,越发觉得写文档也是一项相当重要的工作。文档和代码,对于提高团队协作能力和个人深入思考帮助非常大: 要接受新东西、新思维、新想法。。。

当懂得用另外一种视角的人的想法去考虑同样的问题,  我发现这很美。