不斷出現的卡片掠奪黑客攻擊只是一個特別引人注目的目標。

梅西百貨（Macy's）已警告客戶，入侵者將于10月7日在其網站上將代碼（據信為JavaScript）滑入兩頁，讓他們從購物者那里收集數據，包括姓名，地址和付款信息。

梅西百貨在10月15日發現該攻擊后立即將其關閉，但尚不清楚有多少人受到了影響。該公司告訴Bleeping Computer，一小部分人是受害者，并且已經實施了“附加安全措施”并提供免費信用監控。

這項名為Magecart的技術因其相對簡單和有效的結合而在黑客中越來越流行。他們不需要做很多事情，而只需插入流氓腳本（指向遠程命令和控制服務器）并等待人們購物。從那里，他們可以使用該信息進行欺詐性購買，制作克隆卡并在黑市上出售數據。

不要指望這些攻擊會在短期內消退。它們已被用于眾多主要品牌，包括英國航空，Newegg和Ticketmaster。直到網上商店對諸如Magecart之類的技術保持封閉，它們才會成為誘人的目標。

這篇文章中，本文作者分享了他對于產品文檔的看法以及撰寫產品文檔的常用流程。

產品文檔撰寫指南

很多人聽到「產品文檔」這四個字就像吞了蒼蠅一樣，人們通常會認為這意味著又要花幾周寫一個根本沒人看的文檔。如果一個團隊總被產品文檔這種事情拖累，怎么可能「敏捷」得起來，怎么可能高效地產出代碼？

我在過去十幾年創造了多個數百萬人使用的軟件產品之后，越發認為這種觀點是完全錯誤的。根據我的經驗：

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

在這篇文章中，我會通過一個案例來分享一些普適的建議，這些建議會對大中型（超過二百人的）公司中的產品經理們非常有幫助。

首先，舉個例子

假設你在這里工作：

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

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

通過在支付環節增加在線客服來嘗試提高支付轉化率。支付轉化率目前僅有 18％，而業內平均轉化率有 30％。我們打算測試下在支付時展示在線客服聊天窗口是否可以提高這個轉化率。用戶運營團隊已經同意了提供 1 人月的客服人力支持。

在你沒有產品文檔時，你會這樣做：

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

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

搞定了！這么簡單的事情怎么能要我們寫產品文檔呢？如果你是在一個小型創業團隊，你也確實并不需要——因為產品改動相對小，涉及到的人也相對更少。

但如果你是在一個更大的組織之中，或者產品更加成熟/復雜，就會陸續出現下列這些問題，并且相比寫文檔，這些問題會需要更多時間來處理。

例如：

• 工程師把工單標記完成了，但是一驗收測試，就發現這個功能完全沒有考慮移動端的適配。「唉呀！你忘了提醒大家手機端的使用才是核心場景。」
• 用戶運營經理打算開展一個漫長的評審流程，以確定最合適的聊天服務商。「啊……需要定一個會議，向大家解釋下這次上線只是一個灰度測試。」
• 發布一小時后，客服報告說他們收到了西班牙語的在線聊天請求。「啥？要追加一個緊急發布，把這個測試限定在英語用戶中。」
• 一個設計師花了幾天，為聊天窗口滑入屏幕的交互繪制了一個完美的動畫。「用戶體驗過度優化，你是否對整個團隊統一了「這次只是一個測試」的預期？」
• 一周的測試完成之后，數據分析師發現無法產出你要的報告，因為相關的必要指標并沒有埋點。「史詩級的失敗。從頭再來吧。」

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

如果你寫了一篇文檔

為了便于說明，我準備了兩個示例文檔：一篇思路筆記，和一篇完整的產品文檔示例——這樣可以完整介紹產品文檔的撰寫流程。

請在繼續閱讀文章之前，花幾分鐘讀一下這兩篇示例文檔吧。

這是一個根據你已知的信息和想要解答的問題所梳理成的列表。

這會是你需要做的第一件事情，大約需要一個小時來完成這個文檔。這個文檔會成為你和團隊中其他人的一個溝通基礎。

只有和團隊一起評審了你的假設和創意之后（無論是在專門召集的會議上，喝咖啡時，或者桌上足球的休息時間），你才應該真正開始寫產品文檔。

如果已經完成了溝通和評審，整個文檔應該花費你 1-3 個小時的時間。

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

等等！——你已經讀完示例文檔了么？請務必先讀完它再繼續閱讀下面的文章。

Ben Horowitz

文檔撰寫指南

我通過示例文檔詮釋了這篇文章中所講述的思考，在繼續閱讀全文之前，請務必確認你已經閱讀了示例文檔 。

為什么要寫產品文檔？

為了以更高的質量、更快的速度和更佳的預判來交付正確的產品。

是的，就是這樣。那么，產品文檔將如何幫助你做到這一切呢？Ben Horowitz 分享了上圖中這個看法，我的示例文檔也是一個很好的例證。明確一下要點：

1. 從一開始就理性思考：在團隊開始付出更高成本去設計軟件架構、實施代碼開發、完善界面設計、測試軟件質量之前，寫文檔可以迫使你提前思考每一個細節。這將會提高你決策的質量，降低意外事件發生的概率。
2. 高效溝通：你常常需要和不同的利益相關方（支持團隊，工程團隊，設計團隊，財務團隊，管理層等等）溝通你的方案。產品文檔可以幫助你事半功倍地完成溝通，避免口頭溝通中產生的歧義，團隊中的所有人可以更好地理解你的意圖，并且更有的放矢地做出答復。
3. 明確權責：明確項目目標的評價標準，公開承諾獎懲激勵機制：利益相關方可以知曉如果最后一刻變更需求會意味著什么，工程師們也會在預估工期時再三斟酌。

產品文檔中應當包含哪些內容？

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

1. 問題：描繪你此次打算解決的問題。更重要的是，解釋為什么要去解決這個問題。描述要盡可能地具體，并且提供相關的數據指標。
2. 可衡量的目標：明確承諾交付和成果，明確哪些事情超出了此項目的范疇。每一個目標，都應該可以明確衡量「是否達到目標」。
3. 需求背景：提供你的觀眾理解當前問題以及接受你的提議所需的所有背景信息。包括但不限于假設、用例、數據指標等信息。
4. 解決方案詳情：你的提議應該有充足的細節，易于團隊成員消化理解及執行——可以把這部分內容想象成對人腦進行編程和執行。
5. 時間軸：列出你的團隊共同認可的截止日期和其他重要時間點。這部分內容開始的時候可能會比較模糊，但是在最后一次文檔評審之前應當完全敲定。

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

如何寫產品文檔？

接下來我會介紹我撰寫和評審文檔的常規流程。根據項目大小，利益相關方的數量不同等情況，流程細節可能會有所變化，但是大體的流程是確定的。

（1）快速完成一個草稿（1-2 個小時）

關閉電子郵件和聊天工具。泡杯茶，坐在椅子上開始思考，然后逐一把你所了解的信息列成清單（見上文中的思路筆記示例）。

（2）安排幾個 30 分鐘的一對一會議 （1-4 個小時）

這個步驟的目的是過一遍文檔中的細節，優化你的方案，并且獲得更多人的支持。盡可能控制這些會議的規模，人越少越好（理想狀態下都應該是一對一會議）。

在本文的示例中，我會和客服部門的負責人，一個財務人員和一個工程師分別安排一次會議。

（3）撰寫和編輯文檔 （0.5-3 天）

此時，你應該對能做，并且應該做什么有了一個明確的想法，但是大腦中塞滿了大量的細節等待著梳理清楚。于是接下來需要將所有這些細節都整理出來，并且逐一梳理斟酌。

在完成第一版文檔之后，需要繼續大篇幅編輯修改，通常最終的文檔可以在你的第一版草稿的基礎上壓縮 30%-50% 的長度，簡潔和清晰的文檔就意味著更加容易閱讀。

大部分文檔都可以在半天到一天的時間里完成，不過實際上也會有一些文檔需要兩三天才能寫完。

（4）群發文檔并且安排一個 1 小時的評審會議（15 分鐘）

將文檔群發給項目的所有利益相關方，并且抄送給其他可能對文檔感興趣的團隊（例如你所在的產品團隊，整個支持團隊等）。

跟進這些關鍵人員是否接受了會議邀請：將會執行這件事情的人，和所有對這件事情有通過/否決權力的人。

（5）評審文檔（1小時）

在開始會議之前，詢問是否有參會者沒有詳細閱讀你的文檔。通常都會有一兩個人中槍，在這種情況下可以說：「沒問題，我們先用 10 分鐘一起來看一下文檔。已經讀過文檔的人可以利用這個時間先放松休息一下」。

這次會議上你需要獲得利益相關方的同意，并且獲得執行方（工程師、支持團隊等）的知曉、認可以及人力支持。

你可能需要開多次評審會議，并且根據評審會議上溝通的信息不斷修改文檔。

（6）通過評審后，及時同步信息和建立工單 （1-2 小時）

會后同步信息的電子郵件需要包含更新后的產品文檔鏈接，和此項目相關的工單鏈接（例如「在頁面上添加 JavaScript 代碼」，「完成數據分析報告」，「測試 Staging 環境」，「和支持團隊預演流程」，等等）。

一般接下來將會有一位工程師完成技術文檔，不過并不總是這樣（文中的示例項目就不需要這一步）。

寫出高效產品文檔的進階技巧

盡量簡短

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

使用平白的語言和簡單的格式

使用簡短而不是花哨的語句，使用列表和加粗強調可以使文章更一目了然，以放松有趣的方式寫作而不是一板一眼，如果你有得體的幽默感就再好不過了。

為開發團隊預留時間

通過評審并且達成一致通過的文檔才是完善的文檔。如果你希望在未來的某一個迭代 Sprint 中開發此項目，就應該提前兩到三周開始這個產品文檔寫作流程。

像工程師一樣思考

在項目得以進入開發之時，常常會發現大量未預料到的邊緣情況——但這種情形其實可以避免。如果你認真考慮過項目進入開發的所有必要條件，你就可以提前發現這些問題（例如，是否在移動設備中可以使用在線聊天功能？）。

確保每一個人都跟上了你的節奏

當我組織產品評審時，會議室里的大部分人都已經大致了解我要講的內容——因為我已經提前在討論會和日常聊天中溝通過這個事情了。既然大家都已經清楚了「做什么」和「為什么要做」的問題，文檔評審會上我們只要關注實施細節就好了。

在圖表中下功夫

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

在思考和寫文檔上花 0.5-3 天時間

具體時間根據項目大小而定。花費在寫文檔上的時間越長，所帶來的邊際收益就會遞減。特別需要指出的是，沒有人能夠讀的下去超過 5-6 頁的文檔。

指明方向，明晰愿景

你不僅僅是在定義一個功能，也是在解釋「為什么我們要做這件事情」以及「我們的目標是什么」，在文檔中指出這個項目將會對更高層面的規劃造成什么影響，以及接下來會發生什么。

確保你的觀眾閱讀了文檔

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

獲取真誠的反饋

你的文檔是否是在贅述人盡皆知的事情？或者是文檔缺乏足夠的細節？是否在后續實施中發現了太多的邊緣情況？又或者，是否在制定計劃和文檔評審上耗費了太多的時間？你應該和你的團隊時刻保持溝通。

說好的敏捷開發（Agile/Scrum）呢？

我知道會有爭議，但是產品文檔和敏捷宣言的原則沒有絲毫沖突，并且在類似于 Scrum 這樣的敏捷方法上得到了充分發揮。

畢竟，用戶故事（Story）許多時候需要詳盡的描述，文檔可以增加溝通中的清晰度和可傳播性，為什么非要刻板地認為僅僅使用口頭溝通和使用白板才算是敏捷開發呢？

「產品文檔會導致發布變慢，過度規劃，通常會浪費時間」的想法完全是無稽之談。

我工作過的多個世界級團隊遵循著一些敏捷原則（例如兩周一個迭代周期），每天（甚至更頻繁地）發布代碼，并且以發布產品（而不是文檔或者會議）作為衡量成功的標準——這些團隊也都仍然認為文檔是他們打造成功軟件的一個關鍵部分。

你對技術文檔怎么看？

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

總結

感謝你讀到這里。如果你認為這篇文章有用，請分享給其他人——特別是你的產品/工程團隊。

如果你想看更多的產品經理內容（例如：規劃產品路線圖），或者想了解其他人如何使用產品文檔， 請用兩分鐘填寫這個小調查（英文）。我會在未來的文章中分享調查結果中有意思的信息。

以上，祝寫文檔愉快！

備注

1. 感謝周思博（Joel Spolsky） （微軟早期 PM，曾參與創辦 Stack Overflow，Trello，FogBugz 等產品，《軟件隨想錄》作者）的「文檔是對人腦的編程」的比喻。早在2000年，他寫了4 篇關于文檔的系列文章（英文），這對我的 PM 道路產生了巨大的影響，強烈推薦。
2. 在頂部的引文中，貝索斯所說的筆記是指為高層管理會議使用的，介紹新業務/產品創意的備忘錄。這實際上不算是產品文檔，但是兩者并不是完全不一樣。貝索斯在會議開始的時候會組織所有人默讀文件——這激發了我在文檔評審時做同樣的事情。來源
3. 感謝 iDoneThis 博客這篇關于寫作的價值的文章（英文）。這是貝索斯和 Horowitz 的引言的來源。
   感謝 Vikram Oberoi 。

原文作者：Gaurav Oberoi是 SurveyMonkey 的（前）聯合創始人，曾于 Amazon、Xmarks 先后從事工程師、產品經理等職位，在西雅圖和硅谷有十余年的工作經驗。

原文地址：https://goberoi.com/on-writing-product-specs-5ca697b992fd

翻譯：Tomy

譯文地址：http://zhuanlan.zhihu.com/p/23778590

本文由 @Tomy 授權發布于人人都是產品經理，未經作者許可，禁止轉載。

元素共有5個，分別是::before、::after、::first-letter、::first-line和::selection

first-letter

::first-letter主要用于為文本的首字母添加特殊樣式

注意：::first-letter 偽元素只適用于塊級元素。

first-line

::first-line 偽元素用于向文本的首行添加特殊樣式。

注意：::first-line 偽元素只能應用于塊級元素。

selection

::selection 偽元素匹配用戶選擇的元素部分。也就是給我們鼠標滑動選中的部分設置樣式，它可以設置以下屬性

• color
• background
• cursor
• outline

before/after

::before用于在元素內容之前插入一些內容，::after用于在元素內容之后插入一些內容，其他方面的都相同。寫法就是只要在想要添加的元素選擇器后面加上::before或::after即可，有些人會發現，寫一個冒號和兩個冒號都可以有相應的效果，那是因為在css3中，w3c為了區分偽類和偽元素，用雙冒號取代了偽元素的單冒號表示法，所以我們以后在寫偽元素的時候盡量使用雙冒號。

這些添加不會出現在DOM中，不會改變文檔內容，不可復制，僅僅是在css渲染層加入。所以不要用:before或:after展示有實際意義的內容，盡量使用它們顯示修飾性內容，例如圖標。

舉例：網站有些聯系電話，希望在它們前加一個icon?，就可以使用:before偽元素.

二、content屬性

不同于其他偽元素，::before和::after在使用的時候必須提供content屬性，可以為字符串和圖片，也可以是空，但不能省略該屬性，否則將不生效。

偽類元素的display是默認值inline，可以通過設置display:block來改變其顯示。

content可取以下值。

1、string 書名號

使用引號包一段字符串，將會向元素內容中添加字符串。如：a:after{content:""}

舉例：

<!DOCTYPE html><meta charset="utf-8" /><style type="text/css">
p::before{
    content: "《";
    color: blue;
}
p::after{
    content: "》";
    color: blue;
}
</style>
<p>平凡的世界</p>

2、attr() 鏈接

通過attr()調用當前元素的屬性，比如將圖片alt提示文字或者鏈接的href地址顯示出來。

<style type="text/css">
a::after{
    content: "(" attr(href) ")";
 }
 </style>
 <a href="http://www.cnblogs.com/starof">starof</a>

3、url()/uri() 用于引用媒體文件

舉例：“百度”前面給出一張圖片，后面給出href屬性。

<style>
a::before{
    content: url("https://www.baidu.com/img/baidu_jgylogo3.gif");}
a::after{
    content:"("attr(href)")";}
a{
    text-decoration: none;}</style>
---------------------------
<body><a href="http://www.baidu.com">百度</a></body>    

效果：

4、counter()**調用計數器

調用計數器，可以不使用列表元素實現序號功能。

配合counter-increment和counter-reset屬性使用：

h2:before { 
  counter-increment: chapter; 
  content: "Chapter " 
  counter(chapter) ". " 
 }

代碼:

<style>
body{
    counter-reset: section;
}
h1{
    counter-reset: subsection;
}
h1:before{
    counter-increment:section;
    content:counter(section) "、";
}
h2:before{
    counter-increment:subsection;
    content: counter(section) "." counter(subsection) "、";
}
</style>
------------------------------------------------
<body>
<h1>HTML tutorials</h1>
<h2>HTML Tutorial</h2>
<h2>XHTML Tutorial</h2>
<h2>CSS Tutorial</h2>
<h1>Scripting tutorials</h1>
<h2>JavaScript</h2>
<h2>VBScript</h2>
<h1>XML tutorials</h1>
<h2>XML</h2>
<h2>XSL</h2>
</body>   

效果：

了解更多可參考：https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Counters

三、使用

做出各種圖形效果

舉例：一個六角星

<style>
#star-six {
  width: 0;
  height: 0;
  border-left: 50px solid transparent;
  border-right: 50px solid transparent;
  border-bottom: 100px solid red;
  position: relative;
}
#star-six::after {
  width: 0;
  height: 0;
  border-left: 50px solid transparent;
  border-right: 50px solid transparent;
  border-top: 100px solid red;
  position: absolute;
  content: "";
  top: 30px;
  left: -50px;
}
</style>

<body><div id="star-six"></div></body>

#star-six的div是一個正三角行，#star-six::after是一個倒三角形，通過絕對定位，調整其位置即可實現六角星的效果。

打印網頁的URL

<style>
@media print {
  a[href]:after {
    content: " (" attr(href) ") ";
  }
}
</style>
<body>
<a href="http://www.baidu.com">百度</a>
</body>  

圖標

舉例：網站有些聯系電話，希望在它們前加一個icon?，就可以使用:before偽元素，如下：

<!DOCTYPE html><meta charset="utf-8" />
<style type="text/css">
    .phoneNumber::before {
      content:'\260E';
      font-size: 15px;
    }
    </style>
    <p class="phoneNumber">12345645654</p>

動畫

制作一款特殊的鼠標滑入滑出效果

這個效果還是之前一個朋友從某網站看到之后問我能不能實現，我去那個網站查看了代碼學會的，覺得很有趣，特意分享給大家。

可以先看一下效果

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport"
          content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Document</title>
    <style>

        .h-button {
            z-index: 1;
            position: relative;
            overflow: hidden;
        }

        .h-button:before,
        .h-button:after {
            content: "";
            width: 0;
            height: 100%;
            position: absolute;
            filter: brightness(.9);
            background-color: inherit;
            z-index: -1;
        }

        .h-button:before {
            left: 0;
        }

        .h-button:after {
            right: 0;
            transition: width .5s ease;
        }

        .h-button:hover::before {
            width: 100%;
            transition: width .5s ease;
        }

        .h-button:hover::after {
            width: 100%;
            background-color: transparent;
        }

        .submit {
            width: 100px;
            height: 40px;
            color: #fff;
            line-height: 40px;
            text-align: center;
            background: #00baca;
            margin: 50px;
        }
    </style>
</head>
<body>
<div class="h-button submit">提交</div>
</body>
<script>

</script>
</html>

禁用網頁ctrl+f搜索

有些時候，我們不想要用戶使用ctrl+f搜索我們網頁內的內容，必須在一些文字識別的網頁小游戲里，我們又不想把文字做成圖片，那么就可以使用這個屬性，使用::before和::after渲染出來的文字，不可選中也不能搜索。當然這個低版本瀏覽器的兼容性我木有試，谷歌瀏覽器和safari是可以實現不能選中不可搜索的效果的。

拿上面的示例進行嘗試，可以看到，我們使用偽元素添加的[問題]兩個字，就無法使用瀏覽器的搜索工具搜到。