如何撰寫需求文檔

時間：2023-05-24 00:42:01 | 來源：網(wǎng)站運營

時間：2023-05-24 00:42:01 來源：網(wǎng)站運營

如何撰寫需求文檔：

• 永遠考慮那個擁有更強寫作能力的人
• 工欲善其事,必先利其器
• markdown
• 思維導圖
• 流程圖
• 換位思考
• 這個需求,「不做」
• 閉環(huán)
• 寫作套路
• 鋪墊
• 下定義
• 邏輯清晰
• 說人話
• 視角
• 版本延續(xù)性
• 結(jié)語

Reading makes a full man, conference a ready man, and writing an exact man.

本文節(jié)選自《Springboot實戰(zhàn)紀實-如何撰寫需求文檔》,閱讀時長3min。

永遠考慮那個擁有更強寫作能力的人

如果一個崗位有幾個候選人，永遠考慮那個擁有更強寫作能力的人。無論這個人是設計師、程序員、市場或銷售人員，寫作能力總是可以帶來回報的。有效、簡潔的寫作能帶來有效、簡潔的代碼、設計、郵件、即時通訊等等。

寫作帶來： 更深度的思考，更認真的生活，更清晰的溝通，更有效的社交， 更強大的內(nèi)心。

工欲善其事,必先利其器

君子生非異也，善假于物也

思想固然重要,但是善于借助工具表達自己的思想也很重要。這里介紹一些好用的寫作方面的工具。

Markdown

根據(jù)百度百科-markdown,Markdown是一種輕量級標記語言，創(chuàng)始人為約翰·格魯伯（英語：John Gruber）。 它允許人們使用易讀易寫的純文本格式編寫文檔，然后轉(zhuǎn)換成有效的XHTML（或者HTML）文檔。

Markdown是一種簡單的格式化文本的方法，讓排版變得簡答,在任何設備上看起來都很棒。有道筆記,印象筆記,博客園,vscode,github,碼云等都支持markdown語法。

相關(guān)教程

• Markdown編輯器教程。
  
• 想學 Markdown？這篇文章幫你快速上手。
  

思維導圖

對于某些需求涵蓋功能點較多,后者分支較多場景,使用思維導圖呈現(xiàn)更直觀。比如,這是我整理的考試系統(tǒng)的前期需求的一個思維導圖：










現(xiàn)在有很多工具都支持畫思維導圖:

• processon
• xmind
• 百度腦圖

流程圖

程序員童鞋對流程圖肯定不會陌生,常見程序流程圖設計應該是信手拈來。針對復雜需求,有時候使用語言和文字難以描述清楚。這個時候,流程圖該上場了。










流程圖在整個需求的整理中的核心,他能將產(chǎn)品業(yè)務背后的邏輯展示出來。這個需要你對吃透需求,然后內(nèi)化,加工,再輸出。說句題外話,如果你參與了這個需求,一定要摳細節(jié),流程越細化,越有助于成功的實現(xiàn)需求。。

這里推薦幾個常用的流程圖工具：

• processon
• Edraw
• draw.io【開源】

換位思考

接到需求之后,技術(shù)同學往往會先思考技術(shù)實現(xiàn),然后陷入技術(shù)細節(jié),這也是大多數(shù)技術(shù)人的通病。

在此前的文章《需求管理》中,我曾指出技術(shù)同學要放下傲慢和偏見,跳出技術(shù)思維。這對于需求的理解和整理至關(guān)重要。

跳出技術(shù)思維,然后換位思考,這有助于全方位,多角度的理解需求。一個功能可能由不同的角色人員使用,視角不同,需求不同。你需要像導演拍電影一樣,針對不同角色，一個場景一個場景的拍攝,最終串聯(lián)成一個完整的電影作品。

這個需求,「不做」

懂得拒絕是一門藝術(shù)。

技術(shù)人不是一個沒有靈魂的代碼工具。"這是需求爸爸提的,我沒法拒絕","這是產(chǎn)品爸爸喊做的,不管我的事"。當出現(xiàn)問題的時候,我們經(jīng)常聽到技術(shù)同學這樣說。

不合理的需求,對用戶不友好的需求,低收益,高投入的需求,要敢于拒絕。當然,拒絕也是一門藝術(shù),這就是與人溝通的藝術(shù)。如果經(jīng)過深思熟慮,你能夠給出比較合理的解釋或者提出更有建設性的方案,我想這樣才會更加容易讓人接受。

閉環(huán)

閉環(huán)這個詞,真是互聯(lián)網(wǎng)領域的萬金油。但是,筆者這里特指產(chǎn)品需求邏輯的閉環(huán)。

筆者曾經(jīng)待過一個互聯(lián)網(wǎng)教育創(chuàng)業(yè)公司。因為參與人很多都是TOB行業(yè)經(jīng)驗的人。大家都是知道,TOB公司的產(chǎn)品賣出去很多時候是線下的操作。比如,微軟公司,我做操作系統(tǒng)一流,我贏家通吃。但是,TOC就不一定了,個體用戶更加注重用戶體驗,比如曾經(jīng)的電商百團大戰(zhàn)的競爭,后面的共享單車的競爭,消費者可以直接用腳投票的。

我們做了一個課程官網(wǎng),包括課程展示,訂閱充值的官網(wǎng)。官網(wǎng)上線之后,市場同事也做了宣傳,但是發(fā)現(xiàn)基本上沒人注冊,很多用戶都是讓我們幫忙注冊。經(jīng)過研究發(fā)現(xiàn)了原因:

• 因為集成Azure注冊慢,登錄頁面,而且極不友好。 這導致用戶放棄注冊。
• 官網(wǎng)沒有展示客服咨詢電話,只有一個用戶建議表單。無法實時聯(lián)系客服。

這個案例,很典型。從市場到技術(shù),我們做了很多工作,但是最終效果不理想。最大的愿意就是產(chǎn)品不閉環(huán)。用戶想學習課程,但是登錄和注冊體驗太差,這就已經(jīng)擋住了大部分的用戶。

寫作套路

前面我們講了很多坑和避坑策略,那要如何才能寫好需求文檔呢？

鋪墊

根據(jù)百度百科-鋪墊法。戲劇情節(jié)結(jié)構(gòu)的一種手法。在戲劇的進展中，對于某些將要出現(xiàn)的關(guān)鍵性情節(jié)和起關(guān)鍵作用的人物，必須在事前有所準備、暗示；為情節(jié)的展開，為高潮的到來，醞釀氣氛，作好準備，鋪平道路。這種手法叫埋伏或伏筆。

其實可以簡單理解為背景說明。在需求文檔中,增加一定的背景表述,可以增強事物間的因果聯(lián)系和完整性,不顯突兀。

一般可以在你的需求前增加一個背景交代，










這樣的好處是,其一,讓之前沒有參與的人有個背景認識;其二,為自己后續(xù)的觀點(或者設計思路)提供可信依據(jù),至少不知自己拍腦袋想出來的。

下定義

對于不同的業(yè)務,有時候會有一些專有名詞,或者是你自己了說明某個事物而定義的名詞。如果不做一些定義的解釋,很難理解。比如,在設計IM聊天時候,可能會有一些定義,可以給出定義。

邏輯清晰

需求文檔,不是日記,切記流水賬。排版工整,重難點突出。邏輯清晰,富有層次感。

利用圖表配合文字,有條不紊的表達出合理地邏輯。這樣大家閱讀起來,一目了然。

說人話

針對不同的人群一定要設計不同的話術(shù)

這里的人是指不同的受眾?？紤]到需求文檔面向的對象較多,有技術(shù),業(yè)務,測試等,需要拋棄過于專業(yè)的技術(shù)語言，比如不要出現(xiàn)技術(shù)設計的細節(jié),盡量要用自然語言表達。

說句題外話,其實嚴格意義上,需求文檔可能是要寫兩份,一類是給技術(shù)同學看的,一類是給非技術(shù)同學看的。對于前者,你當然可以用類似抽象的uml圖或者直接給出偽代碼來說明。

視角

子非魚,安知魚之樂

你以為的就是你以為的嗎?很多時候,需求的來源并不單一,比如公司要做一個工單系統(tǒng),這個工單系統(tǒng)的使用者幾乎涵蓋了公司的各個部門。按照"用戶第一"的要求,我們需要考慮到不同業(yè)務方的訴求和用戶習慣。

我們在做需求的時候,就要提前想到。否則,后面的設計一定會違背使用者的意圖。前面,講過的換位思考,或者多角色思考該排上用場了。

在文檔中,如何體現(xiàn)呢？通常,可以按照不通視角來描述。這就是類似程序的switch...case...

切記站在上帝視角看待問題。

版本延續(xù)性

需求文檔很少一次性就讓各方滿意的,或多或少都會有補充和調(diào)整。比較好的習慣是使用修訂版本來記錄。

修訂歷史是一個版本的可追溯源，對需求變更歷程有一個清晰的認識。

新建默認為相應模塊的首次使用，對于文檔的修改以及增加的地方可加入超鏈接，同時在增加與修改的具體地方進行顏色標示或者其他標志來進行區(qū)分，方便其他人員進行查詢。

結(jié)語

寫好一個需求文檔,讓人覺得很專業(yè)有很多東西需要學習。這里筆者只根據(jù)個人多年的工作經(jīng)驗,拋磚引玉,歡迎大家怕批評和斧正。