你好，哈布爾！我叫 Lesha，是 Alfa-Bank 產品團隊的系統分析師。我目前正在開發一個針對法人和個體企業家的新型網路銀行。
當你是分析師時，特別是在這樣的管道中，如果沒有文件和密切合作，你將無法取得任何進展。而文檔總是會引發很多問題。為什麼沒有描述 Web 應用程式？為什麼規範中指出了服務應該如何運作，但它卻根本不那麼運作？為什麼只有兩個人（其中一人是編寫規範的人）能夠理解它？
然而，出於顯而易見的原因，文件不容忽視。為了讓我們的生活更輕鬆，我們決定進行文件品質評估。我們究竟是如何做到這一點的以及我們得出了什麼結論都還在討論中。
文件品質
為了避免在文中重複幾十次“新互聯網銀行”，我將寫成NIB。我們目前有十幾個團隊致力於為企業家和法人實體開發 NIB。在這種情況下，他們每個人要么從頭開始為新服務或 Web 應用程式創建自己的文檔，要么對當前文檔進行更改。透過這種方法，文件原則上可以達到高品質嗎？
因此，為了確定文檔的質量，我們確定了三個主要特徵。
- 它必須是完整的。這聽起來很像船長的說法，但值得注意。它應該詳細描述實施解決方案的所有要素。
- 它必須是相關的。即與解決方案本身的當前實現相對應。
- 應該可以理解。以便使用它的人確切地了解解決方案是如何實施的。
總結一下：完整、最新且易於理解的文件。
Опрос
為了評估文件的質量，我們決定採訪直接接觸文件的人：NIB 分析師。受訪者被要求使用以下方案對 10 條陳述進行評分：「以 1 到 5 的等級（完全不同意 - 完全同意）」。
這些陳述反映了品質文件的特點以及調查作者對 NIB 文件的看法。
- NIB 應用程式的文檔是最新的，並且完全符合其實施。
- NIB 應用程式的實施有完整的記錄。
- NIB 應用程式文件僅用於功能支援。
- NIB 應用程式的文件在提交功能支援時是最新文件。
- NIB 應用程式開發人員使用文件來了解他們需要實現的內容。
- NIB 應用程式的文檔足以了解它們是如何實現的。
- 一旦我的團隊對 NIB 專案進行修訂，我就會及時更新其文件。
- NIB 應用程式開發人員審查文件。
- 我清楚地了解如何為 NIB 專案準備文件。
- 我知道何時編寫/更新 NIB 專案的文檔。
顯然，簡單地回答“從 1 到 5”可能無法透露必要的細節，因此人們可以對每件物品留下評論。
我們透過公司 Slack 完成了所有這些工作 - 我們只是向系統分析師發出了邀請來進行調查。共有 15 位分析師（9 位來自莫斯科，6 位來自聖彼得堡）。調查完成後，我們對這 10 個陳述分別進行了平均評分，然後進行了標準化。
事情是這樣的。
調查顯示，儘管分析師傾向於相信 NIB 應用的實施有充分的記錄，但他們在此並沒有給出明確的同意（0.2）。作為一個具體的例子，他們指出現有解決方案中的許多資料庫和佇列都沒有被文件涵蓋。開發人員可以告訴分析師，並非所有內容都有記錄。但開發人員審查文件的論點也沒有明確的支持（0.33）。這意味著實施的解決方案描述不完整的風險仍然存在。
相關性就更簡單了——儘管再次沒有明確的一致性（0,13），但分析師仍然傾向於認為該文件是相關的。這些評論讓我們意識到，相關性問題更多時候出現在前端而不是中間。但他們沒有告訴我們有關背面的任何資訊。
至於分析師自己是否了解何時需要撰寫和更新文檔，共識更加一致（1,33），包括其設計（1.07）。這裡提到的不便之處是缺乏維護文件的統一規則。因此，為了避免「有人在樹林裡，有人在樹林裡」的模式，他們必須基於已經存在的文件範例來進行工作。因此，一個有用的願望是創建一個維護文件的標準並為其各個部分開發模板。
NIB 應用程式的文件在提交功能支援（0.73）時是最新的。這是可以理解的，因為提交功能支援項目的標準之一是最新的文件。儘管有時仍存在問題，但了解實施情況（0.67）也足夠了。
但受訪者不同意（相當一致）的是，NIB 應用程式的文件原則上只需要提供功能支援（-1.53）。分析師是最常被提及的文檔消費者。團隊的其他成員（開發人員）則很少出現這種情況。此外，分析師認為，開發人員不會使用文件來了解他們需要實現的內容，儘管並非一致（-0.06）。順便說一句，在程式碼開發和文件編寫同時進行的情況下，這也是可以預料到的。
底線是什麼？為什麼我們需要這些數字？
為了提高文件質量，我們決定採取以下措施：
- 要求開發人員審查書面文件。
- 如果可能的話，首先及時更新文件。
- 建立並採用記錄 NIS 專案的標準，以便每個人都能快速了解系統哪些元素以及需要如何準確地描述它們。嗯，開發合適的模板。
所有這些都有助於將文件品質提高到一個新的水平。
至少我希望如此。
來源： www.habr.com
