程序员，如何写好文档？

转载请标明出处，原文地址：http://blog.csdn.net/laoyang360/article/details/51712757 

听说要写文档，程序员的第一反应是：为什么要写文档？不写！程序员的我们善于编码、善于讨论方案、争辩技术，大多不善于交流、尤其不善于写文档。记得我们团队有的童鞋的周报就一句话：修改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。 
但是，即便如此，程序员的要非常重视文档的重要性。