曾經(jīng)被一位年輕人問(wèn)：“我看著Datasheet，就可以畫(huà)原理圖,、PCB,；為什么要我們寫(xiě)文檔?！?/p>

       我竟然一時(shí)語(yǔ)塞,，難道我們真的是教條的學(xué)習(xí)大公司做法,？大公司為什么會(huì)這么強(qiáng)調(diào)寫(xiě)文檔,。而一般的小公司的沒(méi)有這樣那樣的文檔和報(bào)告，不是照樣做設(shè)計(jì),？

一份網(wǎng)上流傳的“華三”的PPT有這樣的描述：

開(kāi)發(fā)人員通過(guò)文檔化的過(guò)程查錯(cuò)補(bǔ)遺,；

便于評(píng)審，在早期發(fā)現(xiàn)技術(shù)上的問(wèn)題,；

后續(xù)階段開(kāi)發(fā)任務(wù)可能由他人承擔(dān),，輸出文檔便于他們開(kāi)展工作；

維護(hù)人員開(kāi)展維護(hù)工作需要,；

文檔是必要的交付件,；

“所有的過(guò)程分析都要形成文檔。我們現(xiàn)在有一個(gè)嚴(yán)重的問(wèn)題是,，大家好像不喜歡寫(xiě)文檔,，對(duì)于需要的實(shí)現(xiàn)方案，通常都是一個(gè)負(fù)責(zé)人在腦袋里想想該怎么實(shí)現(xiàn),，然后郵件或電話(huà)找?guī)讉€(gè)相關(guān)人員討論一下就算可以了,，可能連個(gè)會(huì)議材料或會(huì)議紀(jì)要都沒(méi)有。

而老外可不是這樣的,，他們非常非常重視文檔,，他們認(rèn)為一個(gè)人在腦袋里想的東西是不清晰也不全面的，有時(shí)候心里想的認(rèn)為很正確的方案實(shí)際上可能存在致命缺陷,。他們要求必須把心里的想法形成文檔才能有效的避免這種問(wèn)題,。寫(xiě)文檔的過(guò)程中，可以更加有效的,、更進(jìn)一步去整理您原來(lái)心里的思路,，很多問(wèn)題在您寫(xiě)過(guò)文檔的過(guò)程中您就能發(fā)現(xiàn)；另外,，文檔寫(xiě)作多使用圖表,，浪費(fèi)口水的文字盡量少用,，和我們一起工作的系統(tǒng)工程師在系統(tǒng)架構(gòu)分析中就畫(huà)了五六十張圖，就算看不懂他寫(xiě)的英文,，從圖中我們就能夠很清晰的指導(dǎo)整個(gè)產(chǎn)品的系統(tǒng)架構(gòu),。”——摘自一位華為員工的瑞典出差報(bào)告

可見(jiàn),，文檔是一種促發(fā)思考,，輔助設(shè)計(jì)，查漏補(bǔ)缺,，團(tuán)隊(duì)合作的重要工具

那么我們?nèi)绾巫屛臋n寫(xiě)的規(guī)范而有效呢,？我們不是為了寫(xiě)文檔而寫(xiě)文檔。而是在關(guān)鍵節(jié)點(diǎn),，做有效的關(guān)鍵動(dòng)作,，來(lái)完善設(shè)計(jì)。

“流程+模板,?！笔顷P(guān)鍵：例如，我們?cè)诟鱾€(gè)研發(fā)的關(guān)鍵節(jié)點(diǎn)需要輸出哪些文檔,，這些文檔需要包含哪些內(nèi)容,。顯得尤為關(guān)鍵。

另外,，流程和模板的都是死的,，但是需求和設(shè)計(jì)是活的。當(dāng)現(xiàn)有的模板不能涵蓋新設(shè)計(jì)的時(shí)候,。需要設(shè)計(jì)者根據(jù)需求,，補(bǔ)充現(xiàn)有的模板和流程。例如,，我在設(shè)計(jì)一款刀片服務(wù)器的時(shí)候,，X86系統(tǒng)呢的BIOS開(kāi)始使用SPI接口，且增加ME部分,，如何實(shí)現(xiàn)新系統(tǒng)的雙BIOS切換和升級(jí),，就針對(duì)這個(gè)功能點(diǎn)，專(zhuān)門(mén)增加專(zhuān)題分析文檔,。而部門(mén)原先規(guī)劃的“電源專(zhuān)題”,、“時(shí)鐘專(zhuān)題”、“小系統(tǒng)專(zhuān)題”……并不涵蓋相關(guān)內(nèi)容,。

那么就需要我們?cè)趨⒖寄０宓惹叭朔e累的情況下,，不能只是墨守成規(guī)，還需要大膽優(yōu)化和補(bǔ)充現(xiàn)有文檔體系。

什么樣的文檔是好的文檔：

一個(gè)裝修需求的描述：

不好的設(shè)計(jì)文檔實(shí)例：（平直的陳述）

    房子南北走向,，房子大門(mén)在東側(cè)中間位置,。門(mén)廳長(zhǎng)約3米，寬2米,，門(mén)廳左面是主臥室,，右面是廚房。廚房3米寬,，4米長(zhǎng),，廚房門(mén)對(duì)著門(mén)廳，廚房的頂頭還有一個(gè)北陽(yáng)臺(tái),，與廚房同寬,，長(zhǎng)1米。主臥室寬3米,，長(zhǎng)5米左右,，房間門(mén)對(duì)著客廳?？蛷d與餐廳連為一體,，共7米長(zhǎng),，4米寬,，與客廳相連有一南陽(yáng)臺(tái)，與客廳同寬,，長(zhǎng)1.5米,。餐廳的北面是衛(wèi)生間，衛(wèi)生間與廚房相對(duì),，中間由1米寬,，3米長(zhǎng)的過(guò)道隔開(kāi)；衛(wèi)生間門(mén)對(duì)著過(guò)道,，南墻與廚房的南墻在一條直線(xiàn)上,；衛(wèi)生間為長(zhǎng)方形，南墻長(zhǎng)3米,，另一邊長(zhǎng)2米,。衛(wèi)生間的北面是次臥，同寬,，門(mén)朝著過(guò)道,，次臥長(zhǎng)4米。過(guò)道的北端是書(shū)房門(mén),，書(shū)房南北長(zhǎng)4米,，書(shū)房有一個(gè)一米見(jiàn)方的門(mén)廳，書(shū)房的西墻長(zhǎng)4米,，包括1米長(zhǎng)的門(mén)廳長(zhǎng)度,，西墻把書(shū)房和次臥分隔開(kāi),。門(mén)廳東墻北端90角折向東，長(zhǎng)2米,，把書(shū)房和廚房北陽(yáng)臺(tái)分隔開(kāi),。

優(yōu)化后的設(shè)計(jì)實(shí)例：（只是簡(jiǎn)單地進(jìn)行了分段，閱讀起來(lái)更有層次感更清晰,。同時(shí)修正了“約”,、“左右”等模糊的描述。）

1.房子南北走向,，房子大門(mén)在東側(cè)中間位置,。

2.門(mén)廳長(zhǎng)3米，寬2米,，門(mén)廳左面是主臥室,，右面是廚房。

3.廚房3米寬,，4米長(zhǎng),，廚房門(mén)對(duì)著門(mén)廳，廚房的頂頭還有一個(gè)北陽(yáng)臺(tái),，與廚房同寬,，長(zhǎng)1米。

4.主臥室寬3米,，長(zhǎng)5米左右,，房間門(mén)對(duì)著客廳。

5.客廳與餐廳連為一體,，共7米長(zhǎng),，4米寬，與客廳相連有一南陽(yáng)臺(tái),，與客廳同寬,，長(zhǎng)1.5米。

6.餐廳的北面是衛(wèi)生間,，衛(wèi)生間與廚房相對(duì),，中間由1米寬，3米長(zhǎng)的過(guò)道隔開(kāi),；衛(wèi)生間門(mén)對(duì)著過(guò)道,，南墻與廚房的南墻在一條直線(xiàn)上；衛(wèi)生間為長(zhǎng)方形,，南墻長(zhǎng)3米,，另一邊長(zhǎng)2米。

7.衛(wèi)生間的北面是次臥，同寬,，門(mén)朝著過(guò)道,，次臥長(zhǎng)4米。

8.過(guò)道的北端是書(shū)房門(mén),，書(shū)房南北長(zhǎng)4米,，書(shū)房有一個(gè)一米見(jiàn)方的門(mén)廳，書(shū)房的西墻長(zhǎng)4米,，包括1米長(zhǎng)的門(mén)廳長(zhǎng)度,，西墻把書(shū)房和次臥分隔開(kāi)。門(mén)廳東墻北端90角折向東,，長(zhǎng)2米,，把書(shū)房和廚房北陽(yáng)臺(tái)分隔開(kāi)。

字如不表,、表不如圖：

圖形表述方式理解更容易,，上圖已將房間布局信息很清晰表達(dá)出來(lái)，缺的是尺寸信息,，可以在圖中標(biāo)注或附以文字說(shuō)明,，則能完全表達(dá)清楚。

圖形應(yīng)具有“自明性”,，即只看圖,，大體上就可理解圖意。但不應(yīng)為追求自明性而使圖形過(guò)于雜亂,，必要時(shí)應(yīng)佐以少量的文字說(shuō)明,。

總之磨刀不誤砍柴工,。好的工程師,，文檔寫(xiě)得好是必要條件。