我们为什么要写文档？

菜鸟程序猿问：昨晚就加两行代码，怎么搞那么晚？老鸟程序猿答：思考半小时。写代码一分钟，写注释5分钟，测试半小时，写文档半小时。

今天在朋友圈发了这么一个小段子，大家都表示非常有感触。

这篇文章再给大家分享一下《我们为什么要写文档》

文档的作用：
Ø开发人员通过文档化的过程查错补遗；
Ø便于评审，在早期发现技术上的问题；
Ø后续阶段开发任务可能由他人承担，输出文档便于他们开展工作；
Ø维护人员开展维护工作需要；
Ø文档是必要的交付件，是产品的一个组成部分；

“所有的过程分析都要形成文档。我们现在有一个严重的问题是，大家好像不喜欢写文档，对于需要的实现方案，通常都是一个负责人在脑袋里想想该怎么实现，然后邮件或电话找几个相关人员讨论一下就算可以了，可能连个会议材料或会议纪要都没有。
而老外可不是这样的，他们非常非常重视文档，他们认为一个人在脑袋里想的东西是不清晰也不全面的，有时候心里想的认为很正确的方案实际上可能存在致命缺陷。他们要求必须把心里的想法形成文档才能有效的避免这种问题。写文档的过程中，可以更加有效的、更进一步去整理您原来心里的思路，很多问题在您写过文档的过程中您就能发现；另外，文档写作多使用图表，浪费口水的文字尽量少用，和我们一起工作的系统工程师在系统架构分析中就画了五六十张图，就算看不懂他写的英文，从图中我们就能够很清晰的指导整个产品的系统架构。”——摘自一位华为员工的瑞典出差报告

可见，文档是一种促发思考，辅助设计，查漏补缺，团队合作的重要工具


那么我们如何让文档写的规范而有效呢？我们不是为了写文档而写文档。而是在关键节点，做有效的关键动作，来完善设计。


“流程+模板。”是关键：例如，我们在各个研发的关键节点需要输出哪些文档，这些文档需要包含哪些内容。显得尤为关键。
另外，流程和模板的都是死的，但是需求和设计是活的。当现有的模板不能涵盖新设计的时候。需要设计者根据需求，补充现有的模板和流程。例如，我在设计一款刀片服务器的时候，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米，把书房和厨房北阳台分隔开。

字如不表、表不如图：


图形表述方式理解更容易，上图已将房间布局信息很清晰表达出来，缺的是尺寸信息，可以在图中标注或附以文字说明，则能完全表达清楚。
图形应具有“自明性”，即只看图，大体上就可理解图意。但不应为追求自明性而使图形过于杂乱，必要时应佐以少量的文字说明。



总之磨刀不误砍柴工。好的工程师，文档写得好是必要条件。


硬件工程师要写哪些文档：
除了原理图，PCB之外，我们还需要哪些文档。
0、项目计划，或者项目任务分配。
WBS：工作分解结构（Work Breakdown Structure） 创建WBS：创建WBS是把项目可交付成果和项目工作分解成较小的，更易于管理的组成部分的过程。
WBS是项目管理重要的专业术语之一。WBS的基本定义 ：以可交付成果为导向对项目要素进行的分组，它归纳和定义了项目的整个工作范围每下降一层代表对项目工作的更详细定义
1、需求跟踪表
在需求阶段明确需求，避免需求遗漏，避免需求理解差错，避免意淫需求。
2、总体设计
关键器件选型、方案框图，关键接口选择。
3、专题分析
时钟、电源、接口等等这些常规专题之外，我们还应该针对项目的薄弱点，制定特殊的专题文档。
比如双Flash启动，FPGA专题，一些你开发的电路板特有的，而且可借鉴的电路很少的，都需要做好理论分析，和试验验证。
4、规则驱动表单
不管是自己Layout，还是别人Layout，关键规则，例如电源走向、线宽、热设计要点、时序要求、信号质量要求等等。。。。

即作为Layout设计指导，也作为设计是否满足要求的checklist。
5、测试计划于测试方案
相当于对电路设计要求的一个梳理。在投板之前，就梳理出要测试的一些要点，以及测试的计划和方法。
6、软硬件接口文档
类似于一些软件需要知道的硬件信息的一个梳理和澄清。I2C器件的地址、CPLD作为总线访问的一些寄存器的地址。

7、详细设计文档

从电路的运行环境，电路的原理、关键器件、接口、可靠性、可维修性、可测试性、对外界依耐性：面板背板接口、电源的需求。分别描述电路的设计思路的要点。
下面的目录文字，摘自《百度文库》：
     概述... 8
      背景... 8
      单板功能描述... 8
      单板运行环境说明... 8
      重要性能指标... 8
      单板功耗... 8
      必要的预备知识(可选)8
     关键器件... 9
     单板各单元详细说明... 9
      单板功能单元划分和业务描述... 9
      单元详细描述... 9
         单元1. 9
         单元2. 10
      单元间配合描述... 11
         总线设计... 11
         时钟分配... 11
         单板上电、复位设计... 11
         各单元间的时序关系... 11
         单板整体可测试性设计... 12
         软件加载方式说明... 12
         基本逻辑和大规模逻辑加载方式说明... 12
     硬件对外接口... 12
      板际接口... 12
      系统接口... 13
      软件接口... 13
      大规模逻辑接口... 13
      调测接口... 13
      用户接口... 14
     单板可靠性综合设计说明... 14
      单板可靠性指标... 14
      单板故障管理设计... 14
         主要故障模式和改进措施... 14
         故障定位率计算... 15
         冗余单元倒换成功率计算... 15
         冗余单板倒换流程... 15
     单板可维护性设计说明... 16
     单板信号完整性设计说明... 16
      关键器件及相关信息... 16
      关键信号时序要求... 16
      信号串扰、毛刺、过冲的限制范围和保障措施：... 17
      其他重要信号及相关处理方案... 17
      物理实现关键技术分析... 17
     单板电源设计说明... 17
      单板供电原理框图... 17
      单板电源各功能模块详细设计... 17
     器件应用可靠性设计说明... 18
      单板器件可靠应用分析结论... 18
      器件工程可靠性需求符合度分析... 19
         器件质量可靠性要求... 19
         机械应力... 19
         可加工性... 19
         电应力... 19
         环境应力... 19
         温度应力... 19
         寿命及可维护性... 20
      固有失效率较高器件改进对策... 20
      上、下电过程分析... 20
         上下电浪涌... 20
         器件的上下电要求... 21
      器件可靠应用薄弱点分析... 21
      器件离散及最坏情况分析... 21
         单板热设计说明... 22
         EMC、ESD、防护及安规设计说明... 22
    单板电源、地的分配图... 22
    关键器件和关键信号的EMC设计... 23
    防护设计... 23
    安规设计... 23
      安规器件清单... 23
      安规实现方案说明... 24
         单板工艺设计说明... 24
    PCB工艺设计... 24
    工艺路线设计... 24
    工艺互连可靠性分析... 24
    元器件工艺解决方案... 24
    单板工艺结构设计... 25
    新工艺详细设计方案... 25
         单板结构设计说明... 25
    拉手条或机箱结构... 25
    指示灯、面板开关... 25
    紧固件... 26
    特殊器件结构配套设计... 26
         其他... 26
         附件... 26
    安规器件清单... 26
    FMEA分析结果... 27

其他每个环节都类似的文档，便于设计与记录。总之一个思路：把问题尽早暴露，避免问题遗留到项目的后面阶段。越早发现问题，改正问题，这样解决问题的代价越小。