我们为什么要写文档?

       曾经被一位年轻人问:“我看着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米,把书房和厨房北阳台分隔开。

字如不表、表不如图:

图形表述方式理解更容易,上图已将房间布局信息很清晰表达出来,缺的是尺寸信息,可以在图中标注或附以文字说明,则能完全表达清楚。

图形应具有“自明性”,即只看图,大体上就可理解图意。但不应为追求自明性而使图形过于杂乱,必要时应佐以少量的文字说明。


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

发表评论

登录后才能评论
服务中心
服务中心
联系客服
联系客服
返回顶部