Gaurav Oberoi 是 SurveyMonkey 的（前）聯(lián)合創(chuàng)始人揉阎，曾于 Amazon、Xmarks 先后從事工程師欢揖、產(chǎn)品經(jīng)理等職位反镇，在西雅圖和硅谷有十余年的工作經(jīng)驗。在這篇文章中他分享了他對于產(chǎn)品文檔的看法以及撰寫產(chǎn)品文檔的常用流程窥浪。

Jeff Bezos

產(chǎn)品文檔撰寫指南

很多人聽到「產(chǎn)品文檔」這四個字就像吞了蒼蠅一樣祖很，人們通常會認為這意味著又要花幾周寫一個根本沒人看的文檔。如果一個團隊總被產(chǎn)品文檔這種事情拖累漾脂，怎么可能「敏捷」得起來，怎么可能高效地產(chǎn)出代碼胚鸯？
我在過去十幾年創(chuàng)造了多個數(shù)百萬人使用的軟件產(chǎn)品之后骨稿，越發(fā)認為這種觀點是完全錯誤的。根據(jù)我的經(jīng)驗：

高效的產(chǎn)品文檔是創(chuàng)造偉大產(chǎn)品的過程中所不可或缺的重要組成部分姜钳。
撰寫產(chǎn)品文檔可以強制所有人從項目初始就理性思考坦冠，頻繁溝通，明確權責——所有的這些都會帶來更好的軟件質(zhì)量哥桥，更低的進度風險辙浑，以及更少的時間浪費。

在這篇文章中拟糕，我會通過一個案例來分享一些普適的建議判呕，這些建議會對大中型（超過二百人的）公司中的產(chǎn)品經(jīng)理們非常有幫助倦踢。

首先，舉個例子

假設你在這里工作：

一家從事在線旅游預訂服務 （就像 Hotels 或者 Airbnb 但是規(guī)模更小一些）的公司侠草。目前這家公司的支付轉化率偏低辱挥，所以這個季度大家打算嘗試通過在支付環(huán)節(jié)加入在線客服的方案來提升轉化。

你的工單/用戶故事/路線圖是：

通過在支付環(huán)節(jié)增加在線客服來嘗試提高支付轉化率边涕。
支付轉化率目前僅有 18％晤碘，而業(yè)內(nèi)平均轉化率有 30％。我們打算測試下在支付時展示在線客服聊天窗口是否可以提高這個轉化率功蜓。用戶運營團隊已經(jīng)同意了提供 1 人月的客服人力支持园爷。

在你沒有產(chǎn)品文檔時，你會這樣做：

比方說式撼，你覺得行動起來總是最重要的腮介，因此直接開始動手：

1. 在迭代計劃會上，你和團隊討論了這個需求端衰。
2. 然后你挑選了一個靠譜的第三方客服供應商（例如 SnapEngage ）叠洗。
3. 提交一個工單來讓工程師添加一些 Javascript 代碼。
4. 和支持團隊開個會旅东，確定他們都準備好了

搞定了灭抑！這么簡單的事情怎么能要我們寫產(chǎn)品文檔呢？如果你是在一個小型創(chuàng)業(yè)團隊抵代，你也確實并不需要——因為產(chǎn)品改動相對小腾节，涉及到的人也相對更少。
但如果你是在一個更大的組織之中荤牍，或者產(chǎn)品更加成熟/復雜案腺，就會陸續(xù)出現(xiàn)下列這些問題，并且相比寫文檔康吵，這些問題會需要更多時間來處理劈榨。例如：

• 工程師把工單標記完成了，但是一驗收測試晦嵌，就發(fā)現(xiàn)這個功能完全沒有考慮移動端的適配同辣。
• 「唉呀！你忘了提醒大家手機端的使用才是核心場景惭载『岛」
• 用戶運營經(jīng)理打算開展一個漫長的評審流程，以確定最合適的聊天服務商描滔。
• 「啊……需要定一個會議棒妨，向大家解釋下這次上線只是一個灰度測試『ぃ」
• 發(fā)布一小時后券腔，客服報告說他們收到了西班牙語的在線聊天請求伏穆。
• 「啥？要追加一個緊急發(fā)布颅眶，把這個測試限定在英語用戶中蜈出。」
• 一個設計師花了幾天涛酗，為聊天窗口滑入屏幕的交互繪制了一個完美的動畫铡原。
• 「用戶體驗過度優(yōu)化，你是否對整個團隊統(tǒng)一了「這次只是一個測試」的預期商叹？」
• 一周的測試完成之后燕刻，數(shù)據(jù)分析師發(fā)現(xiàn)無法產(chǎn)出你要的報告，因為相關的必要指標并沒有埋點剖笙。
• 「史詩級的失敗卵洗。從頭再來吧∶诌洌」

如果這是一個相對簡單的項目过蹂，即使沒有產(chǎn)品文檔可能也不至于陷入這樣的災難之中。但是在簡單的項目中你仍然有可能會因為沒有文檔浪費許多時間和機會成本聚至。

如果你寫了一篇文檔：

為了便于說明酷勺，我準備了兩個示例文檔：一篇思路筆記，和一篇完整的產(chǎn)品文檔示例——這樣可以完整介紹產(chǎn)品文檔的撰寫流程扳躬。
請在繼續(xù)閱讀文章之前脆诉，花幾分鐘讀一下這兩篇示例文檔吧。

• 閱讀示例思路筆記贷币。（閱讀時間 2 分鐘）
  這是一個根據(jù)你已知的信息和想要解答的問題所梳理成的列表击胜。
  這會是你需要做的第一件事情，大約需要一個小時來完成這個文檔役纹。這個文檔會成為你和團隊中其他人的一個溝通基礎偶摔。

• 閱讀示例文檔。 （閱讀時間 6 分鐘）
  只有和團隊一起評審了你的假設和創(chuàng)意之后（無論是在專門召集的會議上字管，喝咖啡時啰挪，或者桌上足球的休息時間），你才應該真正開始寫產(chǎn)品文檔嘲叔。
  如果已經(jīng)完成了溝通和評審，整個文檔應該花費你 1-3 個小時的時間抽活。

啊哈硫戈！有了文檔之后是不是就感覺踏實多了？寫文檔看起來是額外的工作成本下硕，但是其實并不是丁逝，高效的文檔可以幫助你和你的團隊節(jié)約時間投入汁胆，并且在交付上線時會更有信心。

等等霜幼！——你已經(jīng)讀完示例文檔了么嫩码？請務必先讀完它再繼續(xù)閱讀下面的文章。

Ben Horowitz

文檔撰寫指南

我通過示例文檔詮釋了這篇文章中所講述的思考罪既，在繼續(xù)閱讀全文之前铸题，請務必確認你已經(jīng)閱讀了示例文檔 。

為什么要寫產(chǎn)品文檔琢感？

為了以更高的質(zhì)量丢间、更快的速度和更佳的預判來交付正確的產(chǎn)品。

是的驹针，就是這樣烘挫。那么，產(chǎn)品文檔將如何幫助你做到這一切呢柬甥？Ben Horowitz 分享了上圖中這個看法饮六，我的示例文檔也是一個很好的例證。明確一下要點：

1. 從一開始就理性思考
   在團隊開始付出更高成本去設計軟件架構苛蒲、實施代碼開發(fā)卤橄、完善界面設計、測試軟件質(zhì)量之前撤防，寫文檔可以迫使你提前思考每一個細節(jié)虽风。這將會提高你決策的質(zhì)量，降低意外事件發(fā)生的概率寄月。

2. 高效溝通
   你常常需要和不同的利益相關方（支持團隊辜膝，工程團隊，設計團隊漾肮，財務團隊厂抖，管理層等等）溝通你的方案。產(chǎn)品文檔可以幫助你事半功倍地完成溝通克懊，避免口頭溝通中產(chǎn)生的歧義忱辅，團隊中的所有人可以更好地理解你的意圖，并且更有的放矢地做出答復谭溉。

3. 明確權責
   明確項目目標的評價標準墙懂，公開承諾獎懲激勵機制：利益相關方可以知曉如果最后一刻變更需求會意味著什么，工程師們也會在預估工期時再三斟酌扮念。

產(chǎn)品文檔中應當包含哪些內(nèi)容损搬？

產(chǎn)品文檔應該明確溝通要做一個「什么」產(chǎn)品，以及「為什么」要這么做。用來說明清楚一個產(chǎn)品的表達方式很多巧勤，但最核心的嵌灰，一定要說清楚這五件事情：

1. 問題
   描繪你此次打算解決的問題。更重要的是颅悉，解釋為什么要去解決這個問題沽瞭。描述要盡可能地具體，并且提供相關的數(shù)據(jù)指標剩瓶。

2. 可衡量的目標
   明確承諾交付和成果驹溃，明確哪些事情超出了此項目的范疇。每一個目標儒搭，都應該可以明確衡量「是否達到目標」吠架。

3. 需求背景
   提供你的觀眾理解當前問題以及接受你的提議所需的所有背景信息。包括但不限于假設搂鲫、用例傍药、數(shù)據(jù)指標等信息。

4. 解決方案詳情
   你的提議應該有充足的細節(jié)魂仍，易于團隊成員消化理解及執(zhí)行——可以把這部分內(nèi)容想象成對人腦進行編程和執(zhí)行拐辽。

5. 時間軸
   列出你的團隊共同認可的截止日期和其他重要時間點。這部分內(nèi)容開始的時候可能會比較模糊擦酌，但是在最后一次文檔評審之前應當完全敲定俱诸。

你可以使用我的示例文檔做你的文檔模板，按照你的想法增/刪/改任何章節(jié)赊舶。只要你能夠清晰并且條理清楚地表述上面提到的這五點信息睁搭，文檔形式并不重要。

如何寫產(chǎn)品文檔笼平？

接下來我會介紹我撰寫和評審文檔的常規(guī)流程园骆。根據(jù)項目大小，利益相關方的數(shù)量不同等情況寓调，流程細節(jié)可能會有所變化锌唾，但是大體的流程是確定的。

1. 快速完成一個草稿（1-2 個小時）
   關閉電子郵件和聊天工具夺英。泡杯茶晌涕，坐在椅子上開始思考，然后逐一把你所了解的信息列成清單（見上文中的思路筆記示例）痛悯。

2. 安排幾個 30 分鐘的一對一會議 （1-4 個小時）
   這個步驟的目的是過一遍文檔中的細節(jié)余黎，優(yōu)化你的方案，并且獲得更多人的支持载萌。盡可能控制這些會議的規(guī)模驯耻，人越少越好（理想狀態(tài)下都應該是一對一會議）亲族。
   在本文的示例中炒考，我會和客服部門的負責人可缚，一個財務人員和一個工程師分別安排一次會議。

3. 撰寫和編輯文檔 （0.5-3 天）
   此時斋枢，你應該對能做帘靡，并且應該做什么有了一個明確的想法，但是大腦中塞滿了大量的細節(jié)等待著梳理清楚瓤帚。于是接下來需要將所有這些細節(jié)都整理出來描姚，并且逐一梳理斟酌。
   在完成第一版文檔之后戈次，需要繼續(xù)大篇幅編輯修改轩勘，通常最終的文檔可以在你的第一版草稿的基礎上壓縮 30%-50% 的長度，簡潔和清晰的文檔就意味著更加容易閱讀怯邪。
   大部分文檔都可以在半天到一天的時間里完成绊寻，不過實際上也會有一些文檔需要兩三天才能寫完。

4. 群發(fā)文檔并且安排一個 1 小時的評審會議（15 分鐘）
   將文檔群發(fā)給項目的所有利益相關方悬秉，并且抄送給其他可能對文檔感興趣的團隊（例如你所在的產(chǎn)品團隊澄步，整個支持團隊等）。
   跟進這些關鍵人員是否接受了會議邀請：將會執(zhí)行這件事情的人和泌，和所有對這件事情有通過/否決權力的人村缸。

5. 評審文檔（1小時）
   在開始會議之前，詢問是否有參會者沒有詳細閱讀你的文檔武氓。通常都會有一兩個人中槍梯皿，在這種情況下可以說：「沒問題，我們先用 10 分鐘一起來看一下文檔县恕。已經(jīng)讀過文檔的人可以利用這個時間先放松休息一下」东羹。
   這次會議上你需要獲得利益相關方的同意，并且獲得執(zhí)行方（工程師弱睦、支持團隊等）的知曉百姓、認可以及人力支持。
   你可能需要開多次評審會議况木，并且根據(jù)評審會議上溝通的信息不斷修改文檔垒拢。

6. 通過評審后，及時同步信息和建立工單 （1-2 小時）
   會后同步信息的電子郵件需要包含更新后的產(chǎn)品文檔鏈接火惊，和此項目相關的工單鏈接（例如「在頁面上添加 JavaScript 代碼」求类，「完成數(shù)據(jù)分析報告」，「測試 Staging 環(huán)境」屹耐，「和支持團隊預演流程」尸疆，等等）。
   一般接下來將會有一位工程師完成技術文檔，不過并不總是這樣（文中的示例項目就不需要這一步）寿弱。

寫出高效產(chǎn)品文檔的進階技巧

1. 盡量簡短
   沒有比這更重要的文檔寫作建議了犯眠。簡潔意味著清晰的思路和溝通，也意味著你的文檔更加易于閱讀和理解——這一點至關重要症革。

2. 使用平白的語言和簡單的格式
   使用簡短而不是花哨的語句筐咧，使用列表和加粗強調(diào)可以使文章更一目了然，以放松有趣的方式寫作而不是一板一眼噪矛，如果你有得體的幽默感就再好不過了量蕊。

3. 為開發(fā)團隊預留時間
   通過評審并且達成一致通過的文檔才是完善的文檔。如果你希望在未來的某一個迭代 Sprint 中開發(fā)此項目艇挨，就應該提前兩到三周開始這個產(chǎn)品文檔寫作流程残炮。

4. 像工程師一樣思考
   在項目得以進入開發(fā)之時，常常會發(fā)現(xiàn)大量未預料到的邊緣情況——但這種情形其實可以避免缩滨。如果你認真考慮過項目進入開發(fā)的所有必要條件势就，你就可以提前發(fā)現(xiàn)這些問題（例如，是否在移動設備中可以使用在線聊天功能楷怒？）蛋勺。

5. 確保每一個人都跟上了你的節(jié)奏
   當我組織產(chǎn)品評審時，會議室里的大部分人都已經(jīng)大致了解我要講的內(nèi)容——因為我已經(jīng)提前在討論會和日常聊天中溝通過這個事情了鸠删。既然大家都已經(jīng)清楚了「做什么」和「為什么要做」的問題抱完，文檔評審會上我們只要關注實施細節(jié)就好了。

6. 在圖表中下功夫
   流程圖刃泡、線框圖等圖表可以通過易于理解的方式提供很大的信息量巧娱，同時也需要消耗非常多的時間來制作這些圖表。

7. 在思考和寫文檔上花 0.5-3 天時間
   具體時間根據(jù)項目大小而定烘贴〗恚花費在寫文檔上的時間越長，所帶來的邊際收益就會遞減桨踪。特別需要指出的是老翘，沒有人能夠讀的下去超過 5-6 頁的文檔。

8. 指明方向锻离，明晰愿景
   你不僅僅是在定義一個功能铺峭，也是在解釋「為什么我們要做這件事情」以及「我們的目標是什么」，在文檔中指出這個項目將會對更高層面的規(guī)劃造成什么影響汽纠，以及接下來會發(fā)生什么卫键。

9. 確保你的觀眾閱讀了文檔
   如果你的文檔又臭又長，或者從來不分享給對應的人虱朵，那你還不如不寫文檔莉炉。務必確保你的文檔被對應的人閱讀了钓账，我上面關于評審開始時留時間給大家讀文檔的建議值得大家參考。

10. **獲取真誠的反饋 **
    你的文檔是否是在贅述人盡皆知的事情絮宁？或者是文檔缺乏足夠的細節(jié)梆暮？是否在后續(xù)實施中發(fā)現(xiàn)了太多的邊緣情況？又或者羞福，是否在制定計劃和文檔評審上耗費了太多的時間惕蹄？你應該和你的團隊時刻保持溝通。

說好的敏捷開發(fā)（Agile/Scrum）呢治专？

我知道會有爭議，但是產(chǎn)品文檔和敏捷宣言的原則沒有絲毫沖突遭顶，并且在類似于 Scrum 這樣的敏捷方法上得到了充分發(fā)揮张峰。
畢竟，用戶故事（Story）許多時候需要詳盡的描述棒旗，文檔可以增加溝通中的清晰度和可傳播性喘批，為什么非要刻板地認為僅僅使用口頭溝通和使用白板才算是敏捷開發(fā)呢？

「產(chǎn)品文檔會導致發(fā)布變慢铣揉，過度規(guī)劃饶深，通常會浪費時間」的想法完全是無稽之談。
我工作過的多個世界級團隊遵循著一些敏捷原則（例如兩周一個迭代周期）逛拱，每天（甚至更頻繁地）發(fā)布代碼敌厘，并且以發(fā)布產(chǎn)品（而不是文檔或者會議）作為衡量成功的標準——這些團隊也都仍然認為文檔是他們打造成功軟件的一個關鍵部分。

你對技術文檔怎么看朽合？

我是一個技術文檔的支持者俱两。產(chǎn)品文檔通常關注 做什么 ，而技術文檔更多關注在如何做 曹步。這兩種文檔為研發(fā)流程中的不同環(huán)節(jié)帶來同樣的清晰視角宪彩，并且都使得工程師（和他們的用戶）身心愉悅。
未來如果大家有興趣的話我可能會寫一篇關于技術文檔的文章讲婚。

總結

感謝你讀到這里尿孔。如果你認為這篇文章有用，請分享給其他人——特別是你的產(chǎn)品/工程團隊筹麸。
如果你想看更多的產(chǎn)品經(jīng)理內(nèi)容（例如：規(guī)劃產(chǎn)品路線圖）活合，或者想了解其他人如何使用產(chǎn)品文檔， 請用兩分鐘填寫這個小調(diào)查（英文） 竹捉。我會在未來的文章中分享調(diào)查結果中有意思的信息芜辕。
以上，祝寫文檔愉快块差！

備注：

1. 感謝周思博（Joel Spolsky） （微軟早期 PM侵续，曾參與創(chuàng)辦 Stack Overflow倔丈，Trello，F(xiàn)ogBugz 等產(chǎn)品状蜗，《軟件隨想錄》作者）的「文檔是對人腦的編程」的比喻需五。早在2000年，他寫了4 篇關于文檔的系列文章（英文） 轧坎，這對我的 PM 道路產(chǎn)生了巨大的影響宏邮，強烈推薦。
2. 在頂部的引文中缸血，貝索斯所說的筆記是指為高層管理會議使用的蜜氨，介紹新業(yè)務/產(chǎn)品創(chuàng)意的備忘錄。這實際上不算是產(chǎn)品文檔捎泻，但是兩者并不是完全不一樣飒炎。貝索斯在會議開始的時候會組織所有人默讀文件——這激發(fā)了我在文檔評審時做同樣的事情。來源
3. 感謝 iDoneThis 博客這篇關于寫作的價值的文章（英文）笆豁。這是貝索斯和 Horowitz 的引言的來源郎汪。
   感謝 Vikram Oberoi 。

原文鏈接：https://goberoi.com/on-writing-product-specs-5ca697b992fd
原創(chuàng)翻譯闯狱，轉載請注明出處