如何睿智地写文档

每个人都要求别人要写详细的文档,但是自己又讨厌写文档。除了写文档特别麻烦之外,还有就是怕自己的思想精华被别人吸收。文档写起来,可能会比开发代码多几倍的时间,甚至是在一些文采蹩脚的人的脑中,根本无从下手。一些设计文档,代码文档,产品文档,都是项目中的精华。

己所不欲,勿施于人。当你沉下心来写文档的时候,同时你也会要求你的下级或者你身边的同事来一起完善这方面。所以多思考,谁会读你的文档,他们的水平怎么样,能够接受你文档里的东西吗,或者说从哪些方面能够更引人入胜。

其实,从某个角度来讲,代码也是文档,而且严格来说,代码就是技术最高文档的升华提炼。一个程序员如果懂得写详细的文档,那么在由文档去写代码都是事半功倍,因为只是一个把文档翻译成代码的过程。正如你同时会中文和英文,写好中文后,在用一定的时间把中文翻译成英文一样。

对于大公司,特别注重流程化管理。大都数的管理员都是坚信详细的文档就是流程化的保证。不存在有个大拿把控一切,不存在有人说离开了这个技术大拿,产品就造不出来,公司就无法运营下去,这是错误的思想。所以管控优秀的文档,人没了继续招人,公司就像铁打的营盘,员工就是流水,一波一波的换来换去,公司永不倒。

当然,对于个人来讲,如果你不想让你的思想暴露出来,同时上司又要求你规范文档,那么你完全可以写得含蓄一些,代码里不要写注释,把自己的逻辑表达的婉转一些。对于一个负责人的程序员,可能对你的要求是这样的。

编写的代码文档非常标准规范(可以不写注释),需要你的头文件和源文件按照代码规范来写,优秀的命名规则,折叠伸缩有序,段落合理,代码优雅,那么我觉得要不要写注释没那么重要。

简单清晰的架构设计文档。你可以用简单的流程图,或者思维导图,不要求你画很多框框,但是可能你需要言简意赅。

编写给别人看的代码,比如SDK上的api函数名。为读者和客户考虑,把你珍贵的时间花在让他更加容易阅读的事情上。

©著作权归作者所有,转载或内容合作请联系作者
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

推荐阅读更多精彩内容