科學(xué)的分析方案文檔的利弊

貓會喵喵，狗會汪汪，雞會什么？

(資料圖片)

機(jī)會留給有準(zhǔn)備的人。

先說點(diǎn)虛（?）的，等我們的需求或者項(xiàng)目出名了、別人需要學(xué)習(xí)需要你給出一波裝逼Time的時候，丟出一個圖文并茂的設(shè)計文檔?？隙ū葋G一個代碼倉庫獲得的敬仰多吧？

或者說點(diǎn)實(shí)在的等回頭職級評審的時候，一個復(fù)雜的需求你都想不起來怎么設(shè)計的了還得現(xiàn)畫流程圖貼代碼貼效果......（噓?。?/p>掌控力

先說說對個人成長的意義，

往日我們提到前端最大的優(yōu)勢 -- 所見即所得。

要說這確實(shí)上手門檻低，比起客戶端的編譯動輒一根煙（就目前來說咱們客戶端需要一個小時編譯，一包煙都抽完了）。服務(wù)端部署還要上云要滾動來看，前端的試錯成本實(shí)在是太低了，這是一個巨大的優(yōu)勢，特別是在試水的時候。

如果用一個模塊的開發(fā)比作一道考試題，我觀察過一些同學(xué)（當(dāng)然包括我自己）都是寫幾行切一下屏幕看看情況，但那就好比推導(dǎo)寫完第一行就去對標(biāo)準(zhǔn)答案一樣。獲得的是很碎片化的思路，長期這樣少了一些 “服務(wù)端式”的錘煉，對較大的模塊或是復(fù)雜場景就很難在腦海中形成一個比較清晰的響應(yīng)。

技術(shù)方案可以在一定程度上起到強(qiáng)制大家先想好再寫的作用，補(bǔ)上這部分練習(xí)。時間久了貌似就能發(fā)現(xiàn)自己能在腦子里推導(dǎo)整個代碼的運(yùn)行狀態(tài)了，這樣bug率就會自然而然的低下來，也更容易做出一些前瞻性的設(shè)計。

當(dāng)然我最初的想法其實(shí)只是留下一份好得設(shè)計文檔可以供以后維護(hù)代碼或者需求或者方案的人能夠知道最初的開發(fā)者到底是怎么思考的，如何設(shè)計的。以及有哪些隱性的問題可以從文檔中找到答案，讓開發(fā)人員的心智負(fù)擔(dān)更低。但近一段時間的思考和詢問讓我覺得上面這些問題也有必要說出來。但是否需要先寫文檔再繼續(xù)開發(fā)這點(diǎn)我覺得到要看具體的落地場景。

試錯

俗話說，船小好調(diào)頭。

我相信大家一定都有這樣的經(jīng)歷：比如我們需要寫一個精巧的多模塊重業(yè)務(wù)的組件。

一開始模塊劃分非常合理，狀態(tài)傳遞井井有條，然后QA提了一個BUG，在X條件下X元素的位置沒有對齊，于是需要補(bǔ)一個透傳鏈路傳到某一個sub組件里，或是Sub組件需要一路開回調(diào)開到頂層之類的。或是你設(shè)計了一個完美的組件，然后PM說，我需要在X條件下加一個X元素位置在X坐標(biāo)，并在后續(xù)的一個月時間內(nèi)增加了Y、Z、α、δ.......

當(dāng)然這還算好得，更坑爹一點(diǎn)的是，可能開發(fā)末期發(fā)現(xiàn)， 誒？？我怎么特么不把這幾個組件抽成一層讓他來負(fù)責(zé) XXX 然后集中在 XXX 里 XXX 呢？------算了來不及了等下次重構(gòu)吧、下個需求在重構(gòu)吧、這特么這么多東西重構(gòu)成本太高PM不會同意的 就這樣吧。

有了更好的思路，卻因?yàn)闀r間和工期卡點(diǎn)的原因無法訴諸實(shí)現(xiàn)，只能被迫補(bǔ)丁上線的感覺，相信我這并不好受。打開beetle看看上線分支，序號都快四位數(shù)了？

而方案就能很好的避免這一切，比如在方案進(jìn)行的過程中發(fā)現(xiàn)了這個問題，可能還沒到模塊設(shè)計階段，后面直接就按更好的方向去設(shè)計了，或者只是改幾個圖就行。因?yàn)檫€沒進(jìn)入Coding階段，進(jìn)行大塊的調(diào)整，一般都沒什么風(fēng)險，就算真有，如果在項(xiàng)目前期提出 叫“風(fēng)險”，在項(xiàng)目末期提出那就變成“事故”了

當(dāng)然文檔不是萬能的，我相信這世上不存在一勞永逸的事情。但我相信這能避免大多數(shù)此類問題，能減少多少會隨著代碼掌控力的提升同步提升。具體怎么做會在下述中展開。

回憶溝通成本與記憶成本

隨著業(yè)務(wù)復(fù)雜度的提升，能夠單打獨(dú)斗的項(xiàng)目會越來越少，更多的項(xiàng)目會要求大家合作進(jìn)行（后端合作也是合作-不是），也有很多時候會隨著時間推移加入進(jìn)來共同開發(fā)，此時有個文檔給新同學(xué)介紹，起碼能節(jié)約本人70%的口舌吧。（特別是我們作為開發(fā)人員口舌也不是特別好得情況下，應(yīng)該也沒人愿意一整天給新同學(xué)講解吧。）

在剛開始的時候，凡事兒寫文檔里再說確實(shí)會在短期內(nèi)提升溝通成本，但是隨著開發(fā)進(jìn)度過半，大家的記憶力開始逐漸衰退的時候，開頭寫的方案可以起到的喚醒記憶的作用就會逐漸凸顯。

代碼之外的額外信息（我認(rèn)為目前最重要的部分）

從代碼中，大部分時候我們只能看到他做了什么事情，但是“不做的事情”其實(shí)也是很重要的信息。比如有時候看代碼你可能會疑惑，這里怎么不做個緩存呢？這里怎么不加個回調(diào)呢？這里為啥......

不做的事情無法通過代碼本身來傳達(dá)，但是如果在方案中有討論，并記錄。就可以很好的解答這部分的疑惑。并且也可以在方案中宣講自己設(shè)計的動機(jī)，不僅講 what 還講 how，加深參與同學(xué)的理解，降低這個同學(xué)的心智負(fù)擔(dān)。就可以避免你設(shè)計的精美的模塊被來支援的同學(xué)隨便加了個跨組件的回調(diào)，再被后來入職的萌新同學(xué)濫用導(dǎo)致最后變成屎山。

When i wrote this, only God and I understood what I was doing.

Now, God only knows

套路化的文檔解決方案（當(dāng)然這是我的套路 - 一家之言）

其實(shí)這個也是一篇文檔，也能看出我的性格和風(fēng)格是比輕松而無拘無束的，（你以為我是瞎寫？其實(shí)我就是瞎寫的。瞎寫又不用有負(fù)擔(dān).jpg）

方案文檔通常要包含一些必要信息，只要信息到位了，章節(jié)標(biāo)題我認(rèn)為可以隨意發(fā)揮。

簡單來說就是：

我要干什么我要怎么干我為什么要這樣干（我為什么不那樣干？）當(dāng)然還有我比較關(guān)注的：你是不是有啥坑需要標(biāo)注一下。

那我們就娓娓道來，這幾部分應(yīng)該如何展開。

我要干什么?

這一階段我想把他稱之為需求分析，隨著我們的level提升，對語焉不詳?shù)男枨蟮某薪幽芰π枰粋€提升。

明確產(chǎn)品的需求

萌新階段，產(chǎn)品：“抄這個”，這種需求要我我肯定懟回去了。（其實(shí)我沒膽子懟，都是鈺哥懟的）。但是很多時候?qū)τ谝恍?fù)雜場景并不是產(chǎn)品自己可以hold住的，也會提前接觸部分技術(shù)同學(xué)進(jìn)行預(yù)研，我們需要把產(chǎn)品不明確的需求轉(zhuǎn)變?yōu)槊鞔_的需求，進(jìn)而轉(zhuǎn)變?yōu)榧夹g(shù)描述的需求。

在小風(fēng)還沒走的時候，他經(jīng)常問我一些問題，大部分都是這種情況。當(dāng)然我感覺我已經(jīng)鍛煉的還可以了。

比如“抄這個”這種需求，我們就可以進(jìn)一步追問來獲取更多細(xì)節(jié)（其實(shí)想想我做的也不好，我大部分說的都是 都可以做排期就行了，但其實(shí)我沒概念。），到比如“你是不是想抄他的這個布局機(jī)制，為了這個機(jī)制有這樣的利這樣這樣的弊，我們可以這樣這樣，你看怎么樣”，這時候我們的段位就高起來了。也能更好的讓我們有更多機(jī)會去接觸產(chǎn)品設(shè)計，讓技術(shù)更多的融入產(chǎn)品。這一過程是一方面是協(xié)助產(chǎn)品明確自己想要的東西到底是什么，另一方面也是幫你自己減少后續(xù)風(fēng)險點(diǎn)。

拆解為技術(shù)點(diǎn)

明確了產(chǎn)品的訴求之后，我們就需要再把產(chǎn)品的需求轉(zhuǎn)變?yōu)榭梢员患夹g(shù)描述的需求。并且先給定優(yōu)先級，有些需要取舍的場景可能會需要這個。

拿之前奢侈品的篩選需求來舉例子，大概就能拆成這么幾塊。

產(chǎn)品想要一個通用的篩選組件（基礎(chǔ)能力）產(chǎn)品想要在這個通用的能力上大有作為做一大堆事情，期望能把配置化做好，能提供解決產(chǎn)品各種各樣稀奇古怪的要求的能力。（明確要做到的技術(shù)點(diǎn)）我要怎么干，我為什么要這么干？（上）

一般寫方案文檔有兩種情形

我基本已經(jīng)有了較為明確的思路，我需要論證他的可行性。我是誰，我在哪，我怎么就tm接了這個活？這玩意兒咋做？毫無思路！

對于第一種，我認(rèn)為，我思考這個問題的時候已經(jīng)有了大致思路，接下來就是在紙上進(jìn)行推演，避免落地后翻車。這種暫時先不展開，后邊會討論到。

那第二種對于一個無從下手的方案，我該如何展開呢？

我認(rèn)為該有這么一節(jié)：【方案思路】

怎么說呢，寫方案之前肯定也沒啥思路，但是隨著這一節(jié)的討論，我的思路會逐漸清晰，我完全明白應(yīng)該怎么做了?。ㄆ鋵?shí)我也沒經(jīng)歷過這一步，后續(xù)的技術(shù)需求可以這么搞。）

梳理核心鏈路

大多數(shù)調(diào)研類需求都會涉及一個“如何打通XX”的問題，這樣的需求大多可以歸納成為一條或多條核心鏈路，然后圍繞著如何確保核心鏈路順利運(yùn)轉(zhuǎn)來展開。所以對于這類需求，第一件事：先畫流程圖。

以我之前做過的停留時長來舉例 - 需求是停留時長，停留時長是怎么被計算的呢？這一套鏈路是什么。如果需要多端適配，那么每個端的這套鏈路如何被打通呢?

組件設(shè)計類方案則不一定會有如此顯著的流程圖，可能更注重模塊劃分，比如比較復(fù)雜的頁面有20個組件，他們之間說是相互獨(dú)立但又有微妙的聯(lián)系，不過即便如此，也并不是沒有核心鏈路，可能是需要提煉。（這一點(diǎn)在和浪總多次的希望zzui能夠提供一些組件時能很好的體現(xiàn)，我們并不能給浪總說我這個需求是啥，而是需要提煉一下，我需要zzui提供一個什么樣的組件，他需要有什么樣的能力，和一個什么樣的API讓我使用。）

這里可能也有一些經(jīng)驗(yàn)層面的判斷在里面，如果大家要是拿捏不準(zhǔn)我覺得可以拋出來大家討論一下。

舉個例子吧

比如篩選組件，核心在于 - 多組件之間的聯(lián)動和數(shù)據(jù)解析。比如停留時長，核心在于 - 計算之后的數(shù)據(jù)應(yīng)該在什么時間節(jié)點(diǎn)發(fā)送且數(shù)據(jù)如何保存。當(dāng)然這還伴隨著多端兼容的問題

篩選組件的核心鏈路

細(xì)化流程

確定了核心鏈路之后，就需要進(jìn)一步細(xì)化了。怎么細(xì)化呢？- 靠捫心自問。

我和一位大佬聊天的時候聽他講過信息論的一些東西，最讓我印象深刻的叫做：“信息是不確定性的減少”。什么意思呢？比如我現(xiàn)在有一個比較復(fù)雜的需求，還需要server的同學(xué)提供一些能力。我需要盤一下手頭的信息，然后整理一波，問問自己要做這個事情還差什么。（到目前為止主要差時間和想法）

比如前期：

是不是要用到一些奇奇怪怪的知識點(diǎn)？比如webRTC、webSocket之類的，我不會？怎么辦？，那方案里標(biāo)記一下我不會（然后學(xué)）比如用到一個第三方的庫或者解決方案，怎么用？不知道。得去看一下。怎么對接服務(wù)端？不知道，需要問服務(wù)端的兄弟或者讓他們給出文檔。

然后上面第一輪問題問了一遍，繼續(xù)問自己第二輪

我和server端的鏈接是否是穩(wěn)固的？斷線了斷網(wǎng)了咋整？服務(wù)端和RTC穩(wěn)固嗎？？

類似這種問題，當(dāng)然第二點(diǎn)貌似看起來不需要我太去關(guān)心，但是我認(rèn)為還是問一下比較穩(wěn)妥。萬一這個問題去問服務(wù)端的同學(xué)說不定他們沒想到但是被你提醒以后風(fēng)險-1

那還可以換個方向問

前端會出現(xiàn)什么意外需要處理嗎？server端會出現(xiàn)什么意外，導(dǎo)致我需要處理嗎？

這些疑問又會讓我們催生出更加完整且有強(qiáng)度的設(shè)計。

還有一些常規(guī)問題。

這套方案的api該怎么設(shè)計。我需要讓別人怎么用，接入成本小一些？如果方案過于復(fù)雜是不是這套方案就行不通？是不是該放棄這個想法？

類似， 總之就是不斷給自己的方案挑刺的過程，用一輪一輪的badcase來惡心自己，看看自己的方案能否扛住。

就我之前停留時長的經(jīng)歷來說，我對于走一步看一步的實(shí)現(xiàn)感到非常的畏懼。一遍一遍的寫出來卻遇到了各種各樣的問題非常折磨人，而且代碼一遍一遍的改，到后邊根本就不在意代碼怎么組織了，只想快點(diǎn)完成這個任務(wù)。

經(jīng)過一輪又一輪的“捫心自問”，我們會發(fā)現(xiàn)一系列的不確定性的東西正在漸漸變少，以往這些沒想明白的點(diǎn)在項(xiàng)目中后期會表現(xiàn)為風(fēng)險，這個項(xiàng)目可能就會相對穩(wěn)的多。

我傾向于用問答的方式來維護(hù)這些問題， 確保是能得到解答的。當(dāng)然我這個是在最后QA環(huán)節(jié)。當(dāng)然也不是所有問題都能找到答案的，解決不了的，那就只能找leader或者拋出來一起討論了。

最終，所有的問題都得到了解答，或者有了臨時方案頂替不至于捅婁子。那這個方案就八九不離十了。接下來我認(rèn)為就進(jìn)入到下一個階段，模塊設(shè)計了。

我要怎么干，我為什么這么干？（下）

同樣的標(biāo)題，用了兩次，是因?yàn)檫@兩部分很多時候是混在一起的起碼是掛鉤的，所以大部分時候他倆都是寫在一起的。至少我貌似就是寫在一起的。

比如，我可以方案思路之后直接形成完備的模塊劃分方案。

那模塊劃分到底是什么呢？前半截的思路部分，其實(shí)是挖掘出需求的全貌，降低不確定性，提升技術(shù)性。而這里的模塊劃分，則更偏向于代碼組織，確保設(shè)計的良好，可行的落地方式。

舉例來說，思路一節(jié)里發(fā)現(xiàn)我們要做的事情有 A,B, CDEFGH。這要這些事全做了，基本這個大需求就穩(wěn)了。但是落地上肯定不能函數(shù)套函數(shù)塞進(jìn)一個文件完事對吧。那其實(shí)我們需要一個邏輯層面的劃分。

我們把每個即將分配的模塊都視為一個個的工人， 我們接下來就需要把之前的ABCDEDF分配給這些人。那怎么分呢？這個就很藝術(shù)了，基于每個項(xiàng)目的具體情況都有極大地側(cè)重點(diǎn)的不同。這個就只能具體項(xiàng)目具體分析了。

舉個例子吧，對于奢侈品來說大部分的能力是通用的，所以奢侈品的組件需要盡可能的通用。但游戲的需求可能更多更靈活，更流程他就更需要更靈活的組件，等等。而且我們應(yīng)該保證一些指標(biāo)，比如現(xiàn)在在提的加載速度優(yōu)化。（我之前設(shè)計篩選的時候就沒有顧及到這個）

模塊劃分需要有多細(xì)呢？

其實(shí)把主要的一些大塊拆出來，能維護(hù)就行了。咱們的需求也沒有大到那么離譜，還記得我前幾個月說的compositionAPI嗎？hooks拆起來啊 同學(xué)們！

紙上談兵到運(yùn)籌帷幄

其實(shí)我說了這么多也在紙上談兵，對于我之前踩到的坑來說，我覺得我可以提供一些想法。

快速展開

首先，寫方案并不是線性的。并不是思路完全好了以后在去寫方案，因?yàn)榍懊嬉蔡岬搅嗽囧e，其實(shí)在方案上掉頭的成本還是挺低的。先列出來一堆問題，在去一個個解決把他們都記下來其實(shí)方案就寫好一半了。

高效傳達(dá)圖片 >> 文字

我們都知道視覺的傳達(dá)比文字更容易理解，所以引入更多的圖，引入更少的直接代碼，都可以很好的幫別人理解你的方案，而良好的圖也可以更好的組織自己的語言。

這也是為什么我認(rèn)為用飛書寫文檔會好一些，因?yàn)閐ashen畫圖的體驗(yàn)實(shí)在是太差了。差到極致了！

這里其實(shí)還有個題外話，以前我畫圖感覺很有包袱，比如流程圖必須圓角矩形起止，菱形判斷節(jié)點(diǎn)，（都是大學(xué)論文害的。）但是我的一個好朋友幫我破除了這個包袱，whatever，我覺得重點(diǎn)應(yīng)該是抓住核心：傳達(dá)信息，只要把想傳達(dá)的信息傳達(dá)到位了，圖其實(shí)丑一點(diǎn)都無所謂。而且不用嚴(yán)絲合縫的畫圖其實(shí)真的挺快的。我上一篇例子文檔的3張圖我原本以為要畫幾十分鐘，結(jié)果10分鐘3張都畫完了。如果不是什么正式場合，這種非標(biāo)準(zhǔn)的圖我覺得大家都可以隨便畫畫，意思到位就行了。不需要有那么多負(fù)擔(dān)。

顏色的使用（構(gòu)想）

畫圖的時候如果有什么側(cè)重點(diǎn)，可以用顏色的變化來解決這個問題。（當(dāng)然我覺得這個可以當(dāng)做職級評審時的一種手段？？）

我覺得效果還是挺明顯的，不過這里有一點(diǎn)，顏色應(yīng)該相對少。因?yàn)槎纪怀?= 都不突出了

回收驗(yàn)證

在方案完畢，開始進(jìn)行開發(fā)以后，也不是把方案就丟一邊了。我覺得應(yīng)該在適當(dāng)?shù)臅r候打開方案再看看當(dāng)時是怎么想的。

一開始我說了對答案的故事？在開發(fā)中也能驗(yàn)證自己的方案設(shè)計水平。

設(shè)計模塊是否按預(yù)期落地了？差別有多大？為什么？

選擇性寫方案/重復(fù)利用

并不是每個需求都要寫方案，一些小需求排期在1、2天我覺得就沒有必要寫。方案應(yīng)該對應(yīng)的是一些自己不能拿到需求就清楚那些東西該劃分成什么樣模塊需要怎么寫的時候才需要寫文檔。

當(dāng)PM反復(fù)在對一次設(shè)計的文檔中的內(nèi)容反復(fù)進(jìn)行迭代時，我們應(yīng)該基于該文檔去維護(hù)，而不是重寫。這樣也能在重復(fù)整理的過程中更加清晰的認(rèn)識這套需求是如何運(yùn)作的，且方案在重復(fù)修改的過程中，也能知道未來對于該項(xiàng)目如何進(jìn)行重構(gòu)。（找到優(yōu)化點(diǎn)進(jìn)行優(yōu)化、是否能更加自動化......）

總結(jié)

-- 設(shè)計階段 --

明確產(chǎn)品需求 背景和為什么寫清楚。為了完成這個需求我們具體要做哪些事情。梳理核心鏈路，這一套實(shí)現(xiàn)的核心鏈路流程是怎么樣的。把鏈路的各個節(jié)點(diǎn)細(xì)化一下，具體我們需要如何實(shí)現(xiàn)這個節(jié)點(diǎn)。

-- 項(xiàng)目組織階段 --

把實(shí)現(xiàn)各個節(jié)點(diǎn)的抽象邏輯細(xì)化到模塊圖。我們?nèi)绾谓M織這個節(jié)點(diǎn)。方案并不是一蹴而就的，他可能是伴隨著你的開發(fā)而編寫的。開發(fā)完以后回頭拿方案驗(yàn)證一下落地效果如何，和方案有什么偏差，在去把方案修正一下這就是一份存根文檔。當(dāng)這個需求有迭代或者功能追增的時候，這個文檔就是你下一篇方案的起點(diǎn)。

PS：過程中遇到各種各樣的意外問題，或者一些不尋常的坑記得備注。不僅要寫how 還要寫why

什么樣的需求需要文檔呢？

舉個例子：

這個需求需要長期維護(hù)這個東西他有一定的復(fù)雜度，他不容易直接從代碼中能窺見整個需求的全貌。這個東西需要提供給第三方使用。這個東西需要各端協(xié)作，有依賴除業(yè)務(wù)側(cè)技術(shù)外的其他關(guān)聯(lián)，如中臺 搜索等。

就這么多~ 大家有問題可以討論下。我在這里只是提供了我的一些思路。文檔這個事情我不能要求大家去寫，我提出了一些問題，也提出了這個解決辦法。希望大家在遇到上述問題時能用方案文檔的解決方案來解決。嘔心瀝血之作！希望大家輕噴～～

關(guān)鍵詞： 我們需要 很多時候 不確定性 各種各樣 解決方案