曾经被一位年轻人问：“我看着Datasheet，就可以画原理图、PCB；为什么要我们写文档。”
我竟然一时语塞，难道我们真的是教条的学习大公司做法？大公司为什么会这么强调写文档。而一般的小公司的没有这样那样的文档和报告，不是照样做设计？
一份网上流传的“华三”的PPT有这样的描述：
开发人员通过文档化的过程查错补遗；
便于评审，在早期发现技术上的问题；
后续阶段开发任务可能由他人承担，输出文档便于他们开展工作；
维护人员开展维护工作需要；
文档是必要的交付件；
“所有的过程分析都要形成文档。我们现在有一个严重的问题是，大家好像不喜欢写文档，对于需要的实现方案，通常都是一个负责人在脑袋里想想该怎么实现，然后邮件或电话找几个相关人员讨论一下就算可以了，可能连个会议材料或会议纪要都没有。
而老外可不是这样的，他们非常非常重视文档，他们认为一个人在脑袋里想的东西是不清晰也不全面的，有时候心里想的认为很正确的方案实际上可能存在致命缺陷。他们要求必须把心里的想法形成文档才能有效的避免这种问题。写文档的过程中，可以更加有效的、更进一步去整理您原来心里的思路，很多问题在您写过文档的过程中您就能发现；另外，文档写作多使用图表，浪费口水的文字尽量少用，和我们一起工作的系统工程师在系统架构分析中就画了五六十张图，就算看不懂他写的英文，从图中我们就能够很清晰的指导整个产品的系统架构。”——摘自一位华为员工的瑞典出差报告
可见，文档是一种促发思考，辅助设计，查漏补缺，团队合作的重要工具
那么我们如何让文档写的规范而有效呢？我们不是为了写文档而写文档。而是在关键节点，做有效的关键动作，来完善设计。
“流程+模板。”是关键：例如，我们在各个研发的关键节点需要输出哪些文档，这些文档需要包含哪些内容。显得尤为关键。
另外，流程和模板的都是死的，但是需求和设计是活的。当现有的模板不能涵盖新设计的时候。需要设计者根据需求，补充现有的模板和流程。例如，我在设计一款刀片服务器的时候，X86系统呢的BIOS开始使用SPI接口，且增加ME部分，如何实现新系统的双BIOS切换和升级，就针对这个功能点，专门增加专题分析文档。而部门原先规划的“电源专题”、“时钟专题”、“小系统专题”……并不涵盖相关内容。
那么就需要我们在参考模板等前人积累的情况下，不能只是墨守成规，还需要大胆优化和补充现有文档体系。
模板
需求
SRS文档
接口文档
设计
概要设计
详细设计
软件设计
移植设计
什么样的文档是好的文档：
一个装修需求的描述：
不好的设计文档实例：（平直的陈述）
房子南北走向，房子大门在东侧中间位置。门厅长约3米，宽2米，门厅左面是主卧室，右面是厨房。厨房3米宽，4米长，厨房门对着门厅，厨房的顶头还有一个北阳台，与厨房同宽，长1米。主卧室宽3米，长5米左右，房间门对着客厅。客厅与餐厅连为一体，共7米长，4米宽，与客厅相连有一南阳台，与客厅同宽，长1.5米。餐厅的北面是卫生间，卫生间与厨房相对，中间由1米宽，3米长的过道隔开；卫生间门对着过道，南墙与厨房的南墙在一条直线上；卫生间为长方形，南墙长3米，另一边长2米。卫生间的北面是次卧，同宽，门朝着过道，次卧长4米。过道的北端是书房门，书房南北长4米，书房有一个一米见方的门厅，书房的西墙长4米，包括1米长的门厅长度，西墙把书房和次卧分隔开。门厅东墙北端90角折向东，长2米，把书房和厨房北阳台分隔开。
优化后的设计实例：（只是简单地进行了分段，阅读起来更有层次感更清晰。同时修正了“约”、“左右”等模糊的描述。）
1.房子南北走向，房子大门在东侧中间位置。
2.门厅长3米，宽2米，门厅左面是主卧室，右面是厨房。
3.厨房3米宽，4米长，厨房门对着门厅，厨房的顶头还有一个北阳台，与厨房同宽，长1米。
4.主卧室宽3米，长5米左右，房间门对着客厅。
5.客厅与餐厅连为一体，共7米长，4米宽，与客厅相连有一南阳台，与客厅同宽，长1.5米。
6.餐厅的北面是卫生间，卫生间与厨房相对，中间由1米宽，3米长的过道隔开；卫生间门对着过道，南墙与厨房的南墙在一条直线上；卫生间为长方形，南墙长3米，另一边长2米。
7.卫生间的北面是次卧，同宽，门朝着过道，次卧长4米。
8.过道的北端是书房门，书房南北长4米，书房有一个一米见方的门厅，书房的西墙长4米，包括1米长的门厅长度，西墙把书房和次卧分隔开。门厅东墙北端90角折向东，长2米，把书房和厨房北阳台分隔开。
字如不表、表不如图：
图形表述方式理解更容易，上图已将房间布局信息很清晰表达出来，缺的是尺寸信息，可以在图中标注或附以文字说明，则能完全表达清楚。
图形应具有“自明性”，即只看图，大体上就可理解图意。但不应为追求自明性而使图形过于杂乱，必要时应佐以少量的文字说明。
总之磨刀不误砍柴工。好的工程师，文档写得好是必要条件。
本站仅提供存储服务，所有内容均由用户发布，如发现有害或侵权内容，请
点击举报。
