研發(fā)工程師(RD)需要撰寫的設(shè)計(jì)文檔主要分為： 總體設(shè)計(jì)文檔 + 詳細(xì)設(shè)計(jì)文檔，后簡(jiǎn)稱為“總設(shè)”+“詳設(shè)”。
總設(shè)和詳設(shè)都應(yīng)該包含的部分：
(1)需求：一般以產(chǎn)品的語言描述，這一塊可以拷貝產(chǎn)品需求文檔中的story list部分;
(2)名詞解釋(可選)：非相關(guān)領(lǐng)域內(nèi)的同學(xué)需要看到文檔需要提前了解的一些概念性質(zhì)的東西;
(3)設(shè)計(jì)目標(biāo)：又分為功能目標(biāo)和性能目標(biāo)，功能目標(biāo)一般是對(duì)產(chǎn)品需求的技術(shù)描述，性能目標(biāo)是根據(jù)產(chǎn)品給出的數(shù)據(jù)對(duì)性能進(jìn)行的評(píng)估。一般來說，新服務(wù)必須要有性能目標(biāo)一項(xiàng)，性能目標(biāo)可能會(huì)影響設(shè)計(jì)方案。
除了都應(yīng)該包含的部分，總體設(shè)計(jì)一般還包含：
(1)系統(tǒng)架構(gòu)：一般來說會(huì)有個(gè)簡(jiǎn)單的架構(gòu)圖，并配以文字對(duì)架構(gòu)進(jìn)行簡(jiǎn)要說明;
(2)模塊簡(jiǎn)介：架構(gòu)圖中如果有很多模塊，需要對(duì)各個(gè)模塊的功能進(jìn)行簡(jiǎn)要介紹;
(3)設(shè)計(jì)與折衷：設(shè)計(jì)與折衷是總體設(shè)計(jì)中最重要的部分;
(4)潛在風(fēng)險(xiǎn)(可選);
輸出總體設(shè)計(jì)的時(shí)候，很多方案還是不確定的，需要在設(shè)計(jì)評(píng)審會(huì)議上確認(rèn)。
總體設(shè)計(jì)重點(diǎn)在“方案折衷”，總體設(shè)計(jì)評(píng)審?fù)戤呏?，此時(shí)應(yīng)該是所有方案都確認(rèn)了，需要輸出各模塊的詳細(xì)設(shè)計(jì)，詳細(xì)設(shè)計(jì)重點(diǎn)在“詳細(xì)”：
(1)總體設(shè)計(jì)結(jié)論匯總(可選)：總體設(shè)計(jì)上達(dá)成一致的結(jié)論有個(gè)簡(jiǎn)要概述，說明詳設(shè)是對(duì)這些結(jié)論的實(shí)現(xiàn);
(2)交互流程：簡(jiǎn)要的交互可用文字說明，復(fù)雜的交互建議使用流程圖，交互圖或其他圖形進(jìn)行說明;
(3)數(shù)據(jù)庫(kù)設(shè)計(jì)：這個(gè)是應(yīng)該放在總設(shè)還是詳設(shè)呢?
(4)接口形式：有了數(shù)據(jù)庫(kù)+接口+流程，別的同學(xué)拿到詳設(shè)文檔，基本也能夠搞定了;
(5)其他細(xì)節(jié)：例如公式等;
理論上輸出了詳細(xì)設(shè)計(jì)之后，無論誰拿到了這個(gè)詳設(shè)文檔，都是能夠完成該項(xiàng)目的。
個(gè)人實(shí)踐分享：
一、大圖
(1)大系統(tǒng)或復(fù)雜流程，其架構(gòu)圖或者流程圖會(huì)非常大，經(jīng)常比A4紙或word的一頁(yè)大很多，此時(shí)不宜在word中直接貼圖形，貼了也看不清，建議將圖放在wiki上，文檔中直接貼鏈接;
(2)一定要保存viso或者其他圖形的 源文件，否則今后改動(dòng)起來要重畫，代價(jià)可想而知;
二、設(shè)計(jì)與折衷
(1)設(shè)計(jì)與折衷是總設(shè)中最重要的內(nèi)容，總設(shè)評(píng)審中，主要就是討論這些 折衷的優(yōu)劣;
(2)評(píng)審過后，不但要郵件周知結(jié)論，還要在總設(shè)中進(jìn)行更新，說明最終決定使用了哪種方案，為什么使用這種方案;根據(jù)自己的經(jīng)驗(yàn)，接手別人的模塊、項(xiàng)目，拿到代碼和文檔，設(shè)計(jì)方案對(duì)我來說完全是個(gè)謎!!!
(3)有時(shí)候因?yàn)榕牌诨蛘咂渌?，不一定采用了最?yōu)的設(shè)計(jì)方案，此時(shí)更應(yīng)該在總設(shè)中記錄決策的過程與原因;
(4)最后，設(shè)計(jì)折衷是一個(gè)很好的自我辯解的機(jī)會(huì)：因?yàn)轫?xiàng)目進(jìn)度，或者歷史遺留問題，我不得不采取了一個(gè)這樣的設(shè)計(jì)，不要再罵我了。
三、性能目標(biāo)
性能目標(biāo)是新模塊文檔必不可少的一部分，很多項(xiàng)目對(duì)性能影響較大的話，也必須撰寫性能目標(biāo)，性能一般來說可能包含以下部分：
(1)日平均請(qǐng)求：一般來自產(chǎn)品人員的評(píng)估;
(2)平均QPS：日平均請(qǐng)求 除以 4w秒得出，為什么是4w秒呢，24小時(shí)化為86400秒，取用戶活躍時(shí)間為白天算，除2得4w秒;
(3)峰值QPS：一般可以以QPS的2~4倍計(jì)算;
互聯(lián)網(wǎng)公司，產(chǎn)品迭代塊，項(xiàng)目周期長(zhǎng)，基本沒有“文檔”一說，但其實(shí)寫好文檔，對(duì)系統(tǒng)和項(xiàng)目未來的維護(hù)是非常有幫助的。
