程序员,如何写好文档?

听说要写文档,程序员的第一反应是:为什么要写文档?不写!程序员的我们善于编码、善于讨论方案、争辩技术,大多不善于交流、尤其不善于写文档。记得我们团队有的童鞋的周报就一句话:修改bug:TDXXXX,TDXXX2,TDXXX3….
那么问题就来了,程序要要不要写文档?为什么要写文档?如何写好文档。

1、文档有哪些?

沟通纪要、会议纪要、周报、工作总结、需求文档、总体设计文档、详细设计文档、单元测试文档、测试用例文档、需求变更文档、产品说明书、项目总结文档等等。
这里写图片描述

2、写文档目的是什么?

你有没有遇到过开晨会、周会的时候某个问题已经讨论的很清晰。但是几天后或者临近周末的时候再说这个问题的时候,团队中有的童鞋会说:“我不知道,没有说过这个问题或者这个方案”,因此而造成的BB事很伤神费心。
为了避免出现问题后的瞎BB,特需要形成文字记录下来。
1)好记忆不如烂笔头,我们讨论很好的方案,有时候只是灵光一闪,尽快记录下来会留住灵感。
2)追根溯源。口头开会的时候,大家各抒己见,貌似已经讨论出方案。但实际每个人的理解各有不同,会后及时形成文档甚至图表,抄收给与会者,便于大家达成共识。如:能清晰界定出责任、明细分工。
3)真正写的时候,更便于梳理思路。如:需求文档会清晰定义每一个客户需求点和要求,是用户利益保障的前提,是甲方、乙方沟通的纽带和桥梁。如:会议纪要是大家会议讨论结果的总结,存在问题、责任人、解决方案明确的基石。如:变更需求的依据,原来需求怎么写的,为什么不满足,原因是什么?如何修改等。

3、文档的痛点有哪些?

1)认为不重视。程序员往往会感觉没必要,能技术实现就ok了,其他不重要。
2)真心不想写。会形成恶性循环,这次不想写,下次、下下次还会如此。
3)感觉没必要。感觉没有必要写,不知道为什么要写,不知道写什么?

4、文档的重要性

1)研发开发根据,功能实现根据

需求明细是开发技术实现的依据,验收时需求矩阵中的每一个点都要覆盖和完善。

2)关乎项目的持续性。

项目管理中有文档归档管理,规划、需求、设计等贯穿项目始终的流程中的所有文档都要归档。便于下一个版本或后续项目开展的很好的依据。新加入团队人员的第一手也是最重要参考文档。

3)是为证据,便于追责

项目中曾经出现过通过甲方、乙方的邮件作为证据对簿公堂的情况。

3、如何写好文档?

3.1提纲挈领

写之前先列出提纲或者参考公司模板文档,包含哪几部分、每个部分的要点是什么都大致想到。
有了轮廓,再动笔去写。

3.2逻辑清晰

尽量不要口语化,要逻辑清晰、主次分明。如:周报好的方式包括:
1)上周工作:逐条列出。
2)上周遇到难题:逐条列出。
3) 上周风险点&待讨论点:概要列出。(会后讨论)
4)本周计划:逐条列出。

3.3图文并茂

需要图、表的地方一定不要省略。比如设计文档中的:架构图、模块图、类图、活动图、流程图等。
比如设计文档中的示例配置.ini、.xml、.conf要以截图或者表格的形式说明字段和含义。
一图胜白文,有图有真相。

3.4同步更新

这点非常重要。如设计方案真正实现的时候可能和文档不一致。实现改了,文档要跟着改。便于自己后续排除问题,也为项目以后的维护者造福。要不别人会看着一头雾水。
如:代码更新了,注释要同步更新。

3.5提供认识

团队乃至公司上下要形成一致方案,非常重视并上行下效。

3.6全局统筹

刚开始程序员的我们可能不适应,但想到利弊得失。要逐步适应。并且高层要全局统筹,做好相应的奖惩措施,提高大家的认识和积极性。

小结:

文档并不可怕,想想我们多复杂的架构头能理顺、多逻辑都能实现,文档也就是小Case。
但是,即便如此,程序员的要非常重视文档的重要性。

2016-06-19 周日 16:18

作者:铭毅天下
转载请标明出处,原文地址:http://blog.csdn.net/laoyang360/article/details/51712757
如果感觉本文对您有帮助,请点击‘顶’支持一下,您的支持是我坚持写作最大的动力,谢谢!

©️2020 CSDN 皮肤主题: Age of Ai 设计师:meimeiellie 返回首页