来源：硬件十万个为什么
菜鸟程序猿问：昨晚就加两行代码，怎么搞那么晚？
老鸟程序猿答：思考半小时。写代码一分钟，写注释5分钟，测试半小时，写文档半小时。
今天在朋友圈发了这么一个小段子，大家都表示非常有感触。
这篇文章再给大家分享一下《我们为什么要写文档》
文档的作用：
Ø开发人员通过文档化的过程查错补遗；
Ø便于评审，在早期发现技术上的问题；
Ø后续阶段开发任务可能由他人承担，输出文档便于他们开展工作；
Ø维护人员开展维护工作需要；
Ø文档是必要的交付件，是产品的一个组成部分；
“所有的过程分析都要形成文档。我们现在有一个严重的问题是，大家好像不喜欢写文档，对于需要的实现方案，通常都是一个负责人在脑袋里想想该怎么实现，然后邮件或电话找几个相关人员讨论一下就算可以了，可能连个会议材料或会议纪要都没有。
可见，文档是一种促发思考，辅助设计，查漏补缺，团队合作的重要工具
那么我们如何让文档写的规范而有效呢？我们不是为了写文档而写文档。而是在关键节点，做有效的关键动作，来完善设计。
“流程+模板。”是关键：例如，我们在各个研发的关键节点需要输出哪些文档，这些文档需要包含哪些内容。显得尤为关键。
| 模板 |
需求 | 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米，把书房和厨房北阳台分隔开。
总之磨刀不误砍柴工。好的工程师，文档写得好是必要条件。
硬件工程师要写哪些文档：
1、需求跟踪表
在需求阶段明确需求，避免需求遗漏，避免需求理解差错，避免意淫需求。
2、总体设计
关键器件选型、方案框图，关键接口选择。
3、专题分析
时钟、电源、接口等等这些常规专题之外，我们还应该针对项目的薄弱点，制定特殊的专题文档。
比如双Flash启动，FPGA专题，一些你开发的电路板特有的，而且可借鉴的电路很少的，都需要做好理论分析，和试验验证。
4、规则驱动表单
不管是自己Layout，还是别人Layout，关键规则，例如电源走向、线宽、热设计要点、时序要求、信号质量要求等等。。。。
即作为Layout设计指导，也作为设计是否满足要求的checklist。
下面的目录文字，摘自《百度文库》：
1 概述
1.1 背景
1.2 单板功能描述
1.3 单板运行环境说明
1.4 重要性能指标
1.5 单板功耗
1.6 必要的预备知识(可选)
2 关键器件
3 单板各单元详细说明
3.1 单板功能单元划分和业务描述
3.2 单元详细描述
3.2.1 单元1
3.2.2 单元2
3.3 单元间配合描述
3.3.1 总线设计
3.3.2 时钟分配
3.3.3 单板上电、复位设计
3.3.4 各单元间的时序关系
3.3.5 单板整体可测试性设计
3.3.6 软件加载方式说明
3.3.7 基本逻辑和大规模逻辑加载方式说明
4 硬件对外接口
4.1 板际接口
4.2 系统接口
4.3 软件接口
4.4 大规模逻辑接口
4.5 调测接口
4.6 用户接口
5 单板可靠性综合设计说明
5.1 单板可靠性指标
5.2 单板故障管理设计
5.2.1 主要故障模式和改进措施
5.2.2 故障定位率计算
5.2.3 冗余单元倒换成功率计算
5.2.4 冗余单板倒换流程
6 单板可维护性设计说明
7 单板信号完整性设计说明
7.1 关键器件及相关信息
7.2 关键信号时序要求
7.3 信号串扰、毛刺、过冲的限制范围和保障措施：
7.4 其他重要信号及相关处理方案
7.5 物理实现关键技术分析
8 单板电源设计说明
8.1 单板供电原理框图
8.2 单板电源各功能模块详细设计
9 器件应用可靠性设计说明
9.1 单板器件可靠应用分析结论
9.2 器件工程可靠性需求符合度分析
9.2.1 器件质量可靠性要求
9.2.2 机械应力
9.2.3 可加工性
9.2.4 电应力
9.2.5 环境应力
9.2.6 温度应力
9.2.7 寿命及可维护性
9.3 固有失效率较高器件改进对策
9.4 上、下电过程分析
9.4.1 上下电浪涌
9.4.2 器件的上下电要求
9.5 器件可靠应用薄弱点分析
9.6 器件离散及最坏情况分析
10 单板热设计说明
11 EMC、ESD、防护及安规设计说明
11.1 单板电源、地的分配图
11.2 关键器件和关键信号的EMC设计
11.3 防护设计
11.4 安规设计
11.4.1 安规器件清单
11.4.2 安规实现方案说明
12 单板工艺设计说明
12.1 PCB工艺设计
12.2 工艺路线设计
12.3 工艺互连可靠性分析
12.4 元器件工艺解决方案
12.5 单板工艺结构设计
12.6 新工艺详细设计方案
13 单板结构设计说明
13.1 拉手条或机箱结构
13.2 指示灯、面板开关
13.3 紧固件
13.4 特殊器件结构配套设计
14 其他
15 附件
15.1 安规器件清单
15.2 FMEA分析结果
其他每个环节都类似的文档，便于设计与记录。总之一个思路：把问题尽早暴露，避免问题遗留到项目的后面阶段。越早发现问题，改正问题，这样解决问题的代价越小。
