> 原文出處：http://www.infoq.com/cn/articles/story-driven-docs 在OutSystems，我們創建了一個平臺，旨在簡化應用程序整個生命周期的管理流程。但是，對于用戶而言，我們的文檔卻不簡單。 我們的文檔側重于描述UI（用戶界面）提供的每個按鈕，而不是用戶的意圖和目的。 一個明顯的例子是，對于文本查找功能（CTRL+F），我們有一整頁的文檔。這頁文檔詳細描述了UI提供的每一種選項，其詳細程度令人難以忍受： * 區分大小寫、不區分大小寫 * 全詞匹配 * 細化搜索范圍 我們專注于這些不言自明的選項，但卻沒有告訴用戶如何找到他們需要的東西： * 如何找出所有具有給定名稱的元素； * 如何找出所有影響標題的CSS規則； * 如何找出所有針對特定數據庫表的查詢。 對我們而言，維護文檔非常困難。OutSystems平臺不斷變化，我們跟不上它的節奏。 更重要的是，我們沒有滿足用戶的需求。這從個位數的頁面訪問量和我們從部分客戶那里得到的反饋很容易看出來。 在本文中，我將討論如何停止編寫UI文檔，并開始提供用戶故事驅動的文檔。 現在，我們專注于用戶想要實現什么以及他們可以如何實現，這與他們需要用到多少窗口或按鈕無關。我們還可以更好地排定工作優先級，那樣一來，最常用的用戶故事會獲得更多的關注和資源。 我將討論以下幾個方面的內容： * 為什么要避免編寫UI文檔； * 如何檢查你當前是否是在編寫UI文檔； * 為什么用戶故事是一種更好的產品文檔編寫方式； * 專注于用戶故事如何改變了我們團隊的文化，使我們可以從事真正重要的工作。 那么讓我們開始吧。 [TOC=2] ## 為什么要避免編寫UI文檔 編寫UI文檔可能使用戶更難以理解你的產品，這顯而易見。這樣做也可能不利于你和你的團隊，但這就不是那么容易理解了。 所以，我們首先重點討論下對用戶的影響，然后再探討下給你和你的團隊帶來的一些后果。 如果你編寫的是UI文檔，即使用戶找到了正確的文檔，他們也無法獲得完成一項任務所需的所有上下文。 這對于新用戶和專家用戶而言都會帶來困難： * **新用戶**——他們無法理解概念之間的關聯關系以及如何搭配使用現有工具解決問題； * **專家用戶**——他們會在查找參考文檔方面遇到困難，因此，他們需要訴諸于試驗。  ## 新用戶的日子會不好過 使用CRTL+F查找什么東西非常簡單，但是大多數任務，比如查詢數據庫表，需要了解若干概念以及它們彼此之間的關聯關系。 因此，對于首次接觸的新用戶而言，即使是簡單的任務，看上去也會很難。以我們的文檔為例，我們有大約13頁文檔解釋如何查詢一張數據庫表。即使新用戶非常有耐心，并且讀完了所有的文檔，他們還是會很難理解如何獲取數據。  更重要的是，他們很難理解如何搭配使用所需的工具在頁面上展示查詢結果。 雖然OutSystems有一個可視化的開發環境，但這還是很讓我失望。這是因為，查詢數據并展示在頁面上只需三次拖放外加兩次鼠標點擊。唉，采用復雜的方式來做，才會這么麻煩。否則，一次拖放就夠了。  ## 專家用戶的日子會不好過 專家用戶的日子也不會輕松。當集中注意力編寫UI文檔時，你很難將需要組織到用戶指南中的信息和應該作為參考的信息區分開。在你看來，所有東西都像參考。 最終，你會將所有的東西都混在一起，即使是經驗豐富的用戶，要找到他們正在查找的詳細說明，也變得更加困難。 ## 搜索引擎很難將流量導向文檔 即使你編寫的文檔適合新用戶及專家用戶，如果用戶無法找到你的文檔，那么你所有的努力也都會白費。 因為當你編寫UI文檔時，文檔的內容和標題反映的是： * 你命名的功能名稱； * 窗口的標題或名稱； * 按鈕標簽。 對SEO（搜索引擎優化）而言，那可能不是最好的選擇。 以我們為例，我們將查找功能的文檔頁命名為“Find Tool”。這個名字僅僅描述了用戶能夠從界面上看到的東西。因此，對于用戶而言，這一頁幾乎沒什么價值。 對于其它的文檔頁，情況也沒多好。由于內容與用戶需求不匹配，所以它最終也沒有包含用戶查找的關鍵詞。因為當你集中注意力編寫UI文檔時，文檔中不會包含用戶查找的關鍵詞，所以文檔在搜索引擎中的排名不夠高，用戶無法找到。 如果沒有一個好的頁面標題，即使文檔排名更高也可能沒用。搜索引擎會將頁面標題作為搜索結果的一部分顯示。如果頁面標題與用戶的心理模型不匹配，那么他們可能不會點擊那個可以將他們導向文檔的鏈接。 ## 你和你的團隊的日子也會不好過 當你編寫UI文檔時，每個任務、窗口和按鈕對你而言都同等重要。 當所有東西的重要性都相同時，就很難排定工作優先級。這很危險，尤其是當你正奔向里程碑時。作為一個副作用，你將會很為難地接受這樣的現實，就是可以不為那些對系統運行而言微不足道的任務編寫文檔。 功能稍有變化（比如按鈕標簽或在界面中的位置稍稍改變），你就會想馬上更新文檔。我不是主張你應該放著文檔不管。但對我們而言，這意味著一個永不完結的文檔維護待辦事項列表。 整個方法讓團隊很難做戰略層面的思考。很快，你就會將更多的精力放在內部流程中，努力縮短文檔維護待辦事項列表，而不是致力于對于用戶而言重要的東西。 ## 如何檢查你是否正在編寫UI文檔 關鍵的問題是沒有客戶或涉眾能夠直接告訴你你正在編寫UI文檔。假如有什么沒能發揮作用，這會讓你更難以準確地找到解決問題的方法。 但從我們的經驗來看，下面一些跡象可能可以說明你正在編寫UI文檔： * 你的客戶抱怨，他們無法將系統中的各個點聯系起來，或者對于如何協調多個可用的工具沒有一個總覽視圖； * 文檔的每一部分都像是參考； * 許多文檔頁描述了相同但稍有變化的內容； * 部分頁面的頁面訪問量或平均閱讀次數一直很少，而對于如何做出改變，你沒有一點頭緒； * 你有一個很長的文檔維護待辦事項列表，妨礙了你做戰略層面的思考。 上述所有癥狀我們都有，但卻不知道做什么才能解決它們。我們認為，所有這些問題都是孤立的，每個問題可以使用單獨的方案來解決。 ## 我們如何開始做出改變 從發現我們正在編寫UI文檔，到弄清楚我們能夠做什么，是一段很長的路。下面，我將簡單介紹一下我們努力改變OutSystems平臺文檔編寫流程和方式的過程。 ### 2012年5月 大約在2012年5月，作為OutSystems平臺的一部分，我們推出了一款新的生命周期管理工具。但這次，我們采用了一種不同的理念來處理這個文檔項目。 我們與開發團隊、產品經理、支持人員坐在一起，收集這個工具處理的用戶故事。我們識別出了大約18個用戶故事，但只有12個是關鍵的。其它6個要么由主用戶故事稍做變化得來，要么是工具未能很好處理的邊緣情況。 我們開始注意到，對于這個項目，排定優先級并不容易。由于用戶故事構建在其它用戶故事的基礎上，我們處理事情的順序很自然地就確定了。隨著最后期限越來越近，我們開始傾向于推遲低優先級的用戶故事。如果有更重要的問題需要處理，那么我們可以在產品發布之后交付剩余的文檔。 另外，我們還傾向于壓根不編寫文檔，而是等待用戶的反饋。 然后，我們有點退步。我們團隊內部發生了一些變化，我們開始設計一個新的在線培訓。這是一個大項目，我們需要將大部分資源都投入進去。因此，在那段時間里，我們無法對文檔做重大修改。 ### 2014年5月 我們正向著下一個主要版本邁進。短暫的失望過后，我們看到可以提供更好的文檔，我與我們的團隊分享了一些我認為令人贊嘆的文檔項目。 我向他們展示，我們可以做得更好，我們只需要投入精力去做。 但我知道，要改變我們交付文檔的方式，這還不夠。因此，我還向團隊展示了，我是如何為我們推出的其中一項主要功能編寫幾乎所有的文檔。我編寫的文檔中只有用戶故事，我并沒有試圖編寫UI文檔。 通過宣傳推動，大家一致同意在為其它旗艦特性編寫文檔時使用用戶故事。但我們沒有創建任何流程或風格指南來確保我們都交付用戶故事。因此，對于部分較小的特性，其文檔中混合了用戶故事和UI。 ### 2014年10月 我們發布了從5月份就開始編寫的文檔版本，我們都累壞了。 我們決定停下來，做一個團隊回顧。每個團隊成員準備一段20分鐘的演講，內容是關于他們在該版本發布之前的6個月里所參與的項目。對于每個項目，每個團隊成員還需要指出三件進展順利的事以及三個還能改進的地方。 我寫過一篇[文章](http://www.joaofn.com/post/outsystems-platform-a-retrospective/)，詳細介紹那次回顧，但總體上我們認為，使用用戶故事讓我們： * 能夠在到達Beta里程碑之前交付文檔； * 現有的文檔得到明顯改善； * 更具生產力，因為更容易排定工作優先級了。 另外，總的來說，專注于用戶故事還使我們團隊同開發團隊之間的討論更專注、更簡單。 我們只是需要結構化我們處理項目的方式，因為每個團隊成員都有自己的流程。結構化將使項目管理更簡單，使我們可以在將來的項目中節省時間。 ## 我們現在的文檔編寫流程 那次回顧之后，我們一致同意使用下面的五步流程進行迭代： * 及早開始，經常對開發團隊進行隨訪； * 檢查是否是開始創建文檔和培訓材料的恰當時機； * 動手測試新特性； * 編寫文檔草稿，并要求涉眾反饋； * 如果需要，進一步修飾文檔并要求反饋。  ## 及早開始并經常隨訪 在OutSystems，開發團隊會在項目開始前主持召開一個項目啟動會議。每個團隊都會邀請我們及其它涉眾，因此，我們知道每個團隊正在做什么。 然后，我們會分析團隊收集的用戶故事，并查看他們創建的設計文檔。如果我們對一個用戶故事有不同意見，那么我們會同開發團隊和產品管理部門一起評審，確保我們只提供最重要的用戶故事。 ## 找出開始編寫文檔的恰當時機 由于大多數團隊都混合使用SCRUM和看板，所以他們還會在每個沖刺之后演示新進展。這些接觸點使我們可以評估團隊有多大進展，并檢查下，開始為新特性編寫文檔及培訓材料是否合適。 時機必須恰當。如果介入過早，那么我們會為容易變化的特性編寫文檔。如果介入太晚，那么我們就有延期交付文檔的風險。更重要的是，我們會冒著無法向開發團隊提供反饋的風險，而他們可能會為用戶創建特性。 ## 測試新特性并反饋 當我們認為時機恰當時，我們從開發團隊那里獲取一個構建版本，并嘗試針對新特性執行用戶故事。 我們實現了一些概念驗證，只是為了通過嘗試找出在文檔中講故事的最佳方式。例如，關于從數據庫提取數據的文檔是否應該關注提取客戶、訂單、票據或其它信息？ 在積累了一些新特性的使用經驗后，我們還會同開發團隊分享我們的反饋。我們可以借此準確地指出什么情況讓新特性難以學習和使用。例如，認識到從多個表查詢數據的方式并不直觀，了解到某個特定屬性的用途，或者一條錯誤消息試圖傳達的信息。 ## 創建文檔草稿 然后，我們開始為新特性編寫文檔草稿。通常，我們會協同使用多種編輯工具，如Google文檔，并避免使用標記、截屏或其它任何讓我們從試圖闡釋的用戶故事分心的東西。 接下來，在我們團隊和實現特性的開發團隊內部將展開一輪“20%”反饋。這輪反饋的目標是，確認用戶故事和我們用于闡釋用戶故事的示例是否明確。 ## 修飾文檔 最后，在我們都認為用戶故事合理、敘事良好之后，我們會評審和修飾文檔。我們會做一些編輯工作，并增加必要的截屏，確保用戶可以獲得他們所需要的所有上下文信息。 接下來是一輪“80%”反饋。此時，技術上的細節也要闡釋清楚，因此，反饋的目標是，確保文檔引入注目、易于閱讀，并且恰當地闡釋了如何完成相關的用戶故事。 ## 我們從這個過程中學到了什么 自2012年開始，我們已經學到了多個重要的教訓。 **小處著手**。將新的小項目作為開始改變的機會。  如果你有東西可以展示， 那么就更容易說服別人跟隨你。早在2012年，我們就完成了第一個文檔項目，我們可以展示一些積極的結果，但無法建立能夠促使我們作出改變的意識。 **不要等到重大項目開始改變**。在完成了應用程序生命周期管理工具的文檔后，我一直希望有個機會重修我們最常用的文檔——我們的IDE文檔。但總有事情妨礙。因此，如果你真得想要改變，那么現在就從你正在交付的新特性開始。然后，你所做的改變將會獲得一些曝光，改革過程會加速，而其它妨礙你作出改變的事情似乎不那么重要了。 **需要有人引導改革過程**。如果你對什么感到失望，不要抱怨，做點什么。  就個人而言，以下幾個方面會讓我感到失望： * 文檔沒有顯示出OutSystems平臺如何強大和易用； * 文檔沒有幫助用戶將系統中的各個點聯系起來； * 不斷增長的文檔維護待辦事項列表阻礙我們進行戰略層面的思考。 我看到用戶故事如何幫助解決所有這些問題，因此，我使用用戶故事為一個旗艦特性編寫了文檔。開始的時候，我從團隊內部獲得的反饋大多數跟不一致有關。但稍后，反饋的內容開始發生變化，現在，使用用戶故事編寫文檔已成常態。 **用戶故事讓我們成為更好的開發后援**。當用戶故事確定以后，你可以在向他人反饋時擺脫直覺的干擾。 經常執行的用戶故事應該易于完成，比如，從數據庫查詢數據。使用不那么頻繁的用戶故事可以難一點、隱蔽一點，比如查看OutSystems平臺為提取數據而生成的SQL。 如果開發團隊實現了什么東西，但卻沒有相應的用戶故事，那么它可能只是“膨脹軟件（bloatware）”，你的產品沒它會更好。就是這一年，我們說服開發團隊放棄了兩項特性，否則，那兩項特性會包含在產品中，但我們99%的客戶都不會用到它們。 ## 這只是開始 到目前為止，我們創建用戶故事驅動文檔的經驗僅僅局限于我們產品中相對比較直觀的部分。我們還有許多東西需要反復學習。 也許，可以使用同樣的方法為框架、API或者開發工具的其它底層特性編寫文檔。或者，用戶故事文檔可能根本就不能用于這些情況。 也許，有比用戶故事更好的東西，但我們尚未發現。 ## 關于作者  **[Joao Fernandes](http://www.joaofn.com/)**是OutSystems的一名研究院工程師，負責創建產品文檔及進行免費在線培訓。他的終極目標是，通過與開發團隊的緊密合作，幫助創建不需要培訓或文檔的產品，從而讓自己無需進行文檔編寫工作。 **查看英文原文:**[User Story Driven Docs](http://http//www.infoq.com/articles/story-driven-docs)