Part.2

這個系列的文章只談需求文檔，不是技術(shù)說明書。總是有人會把這兩者弄混，我不知道標(biāo)準(zhǔn)的術(shù)語是怎樣的，但是當(dāng)我使用這些術(shù)語的時候我是這么理解的：

需求文檔是用來從用戶的角度來描述產(chǎn)品是如何運(yùn)作的，它不關(guān)心你是如何實(shí)現(xiàn)的，在意的只是產(chǎn)品的特性。它指定的是程序內(nèi)的各種功能和界面。

技術(shù)文檔是用來描述程序的內(nèi)在實(shí)現(xiàn)，講的都是數(shù)據(jù)結(jié)構(gòu)、數(shù)據(jù)庫模型、編程語言和工具的選擇和算法等。

當(dāng)你全面地設(shè)計(jì)一個產(chǎn)品的時候，最重要事情就是弄好用戶體驗(yàn)。界面都顯示什么內(nèi)容，內(nèi)容如何運(yùn)作，它們的作用是什么。之后你關(guān)心的是怎么從一個界面跳轉(zhuǎn)到另外一個界面。當(dāng)你還沒決定產(chǎn)品做成什么樣子的時候根本沒必要討論要使用什么編程語言。在這一系列文章里我只討論需求文檔。

我寫了一個簡短的需求文檔樣例來讓你看看一個好的需求文檔應(yīng)該是什么樣子的，在我們繼續(xù)說下去之前，你先去看看這篇文檔：鏈接。

你看了沒？

切，你才沒看，現(xiàn)在去看：鏈接，然后再回來，之后我們可以繼續(xù)談?wù)勔环莺玫男枨笪臋n里應(yīng)該有的和不應(yīng)該有的東西。我等你，謝謝

（耐心等待中...（作者好煩…））

嗯，很好。你回來了。

下面就是一些我會放在每篇文檔里的東西。

一份免責(zé)聲明。純屬自我防御，如果里面里面有段話寫著：“這篇文檔沒有完成”，別人就不會跑到你辦公室然后把你頭咬掉（…）。隨著時間流逝，當(dāng)你的文檔要完成的時候，你就可以把這段話改成：“以我的能力來講，這篇文檔是完成了，但是如果我忘了什么的話，請告訴我~”，同時也提醒我，每一篇需求文檔都需要：

一個且只有一個作者。一些公司認(rèn)為需求文檔應(yīng)該由一個團(tuán)隊(duì)來編寫。如果你試過團(tuán)隊(duì)寫作的話，你就會知道沒有比這更糟糕的折磨了。你的需求文檔應(yīng)該只是歸屬由一個人編寫。如果你有一個大項(xiàng)目，那么就把這個項(xiàng)目拆分成幾個部分，然后每個部分由一個人單獨(dú)編寫。有些公司可能認(rèn)為把一個人的名字寫在文檔上面太自我主義和不夠團(tuán)隊(duì)合作。無稽之談（作者繼續(xù)激動）！人們應(yīng)該擁有和負(fù)責(zé)他們編寫的文檔。如果文檔里有了什么錯誤的話，文檔里要有一個名字來負(fù)責(zé)修復(fù)文檔里的錯誤。

使用場景。當(dāng)你設(shè)計(jì)一個產(chǎn)品的時候，你需要在腦中有一些用戶會如何使用你的產(chǎn)品的場景。否則你會設(shè)計(jì)出一個不適合現(xiàn)實(shí)世界使用的產(chǎn)品。從你產(chǎn)品的用戶挑選，想象一個虛構(gòu)的但是卻很典型的用戶以很典型的方式使用你的產(chǎn)品。這就是使用場景所要包含的內(nèi)容。你的場景越生動逼真，你為你真實(shí)或者想象中的用戶設(shè)計(jì)產(chǎn)品的工作就會完成的越好，這也是為什么我會在情景中加入很多虛構(gòu)的細(xì)節(jié)。

非目標(biāo)需求。當(dāng)你和團(tuán)隊(duì)一起構(gòu)建一個產(chǎn)品的時候，每個人都有他們心愛的特性，沒了這特性他就活不了（…）。如果把這些特性都實(shí)現(xiàn)的話，會花費(fèi)無限的時間和太多的錢。你必須開始挑選特性，最好的辦法就是在文檔中有一個“非目標(biāo)需求”的部分，也就是那些我們不會做的事情。非目標(biāo)需求可能是一個不要的特性，或者是一些更普遍的準(zhǔn)則（比如“這個版本的性能不重要，只要能運(yùn)行就行，慢點(diǎn)沒關(guān)系，在下個版本再進(jìn)行優(yōu)化”）。這些非目標(biāo)需求可能會引起一些爭論，但是越早地理清這些問題越好。

總覽。就像是你文檔內(nèi)容的總綱，它可以是一個簡單的工作流或者是總體結(jié)構(gòu)的討論。大家都會閱讀總覽來對你的產(chǎn)品有個宏觀感覺，之后那些細(xì)節(jié)才會更有說服力。

細(xì)節(jié)，細(xì)節(jié)，還是細(xì)節(jié)。終于來到細(xì)節(jié)這一步了。大部分人會跳過這部分，直到他們需要知道特定的細(xì)節(jié)。在需求文檔里，細(xì)節(jié)是最重要的部分。你會發(fā)現(xiàn)在需求樣例中，對于細(xì)節(jié)發(fā)狂的追求讓我列出了登錄界面的各種錯誤情況。如果郵箱不合法怎么辦？如果密碼是錯誤的怎么辦？所有的這些情況都對應(yīng)著真實(shí)的代碼應(yīng)該怎么寫，更重要的事，這些情況都是一些人一定要做的決定。總有人要決定對于丟失的密碼應(yīng)該是怎樣的策略。如果你不決定，那么就沒辦法寫代碼。需求文檔需要列出這些你做出的決定。

未確定問題。在第一版的需求中留下一些未確定的問題是可以接受。在我寫第一版初稿的時候，我總是會有一些不能確定的問題，不過我會標(biāo)記出他們（使用一種特殊的格式，這樣可以方便我搜索），之后在合適的情況下討論下可能的選擇。隨著程序員們開始工作，所有的這些問題都要被逐一解決（你可以覺得讓程序員先開始做一些簡單的內(nèi)容，然后你之后再解決這些未確定的問題是可以的。壞主意。因?yàn)樵诔绦驅(qū)崿F(xiàn)你的設(shè)計(jì)的時候，總會有更多的問題出現(xiàn)。到時候你解決新的問題的時間還不夠，又怎么能解決之前的老問題？除此之外，你解決重大問題的方式很有可能會對實(shí)現(xiàn)功能的方式產(chǎn)生很大的影響）。

注釋。當(dāng)你在寫一篇需求文檔的時候，記住你有各種各樣的觀眾：程序員，測試，UI等等。在你寫文檔時你可能會想到只對于其中某一類人有用的信息。比如說，對于程序員有用的描述技術(shù)實(shí)現(xiàn)的信息我會寫成“程序員注釋”，UI和測試都不會看這些內(nèi)容，只有程序員會看。我的需求文檔里經(jīng)常包含各種“測試注釋”，“UI注釋”，“程序員注釋”等等。

需求文檔要活著。一些開發(fā)團(tuán)隊(duì)有一種“瀑布流”心態(tài)：我們把程序都設(shè)計(jì)好，寫份文檔，打印出來，甩程序員臉上，然后回家。對于這種情況，我只想說“呵呵呵呵呵呵呵呵呵！”。也就是為什么需求文檔名聲這么差，很多人跟我說過“需求文檔根本就沒用，因?yàn)閴焊蜎]人按上面的來，需求總是不及時更新并且永遠(yuǎn)不會反映到產(chǎn)品上”。不好意思，可能你們的需求是不及時更新并且反映到產(chǎn)品上。但是哥的需求文檔是經(jīng)常更新的好么（…）。在產(chǎn)品開發(fā)的過程中或者有新的決定的時候，我會持續(xù)的更新需求文檔。需求文檔總是反映出我們對于這個產(chǎn)品應(yīng)該如何運(yùn)作的理解的集合。只有在所有的代碼都寫完的時候，我們的需求文檔才會被凍結(jié)。為了讓別人更輕松點(diǎn)，我不會每天都重復(fù)發(fā)布文檔，我會在服務(wù)器上放上一份最新的，這樣大家就可以照著這個做東西。在一些里程碑的時候，我會把有修訂標(biāo)記的需求文檔打印出來給他們看，這樣大家就可以只看有修訂的地方，而不用把整個文檔再看一遍了。