你好，哈布爾！我叫 Lesha，是阿爾法銀行產品團隊之一的系統分析師。現在我正在為法人實體和個體企業家開發一個新的網路銀行。
當您是分析師時，尤其是在這樣的管道中，如果沒有文件並與之密切合作，您將一事無成。文檔總是會引發很多問題。為什麼沒有描述 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）。順便說一下，在程式碼開發和文件編寫並行的情況下，這也是預期的。
底線是什麼？為什麼我們需要這些數字？
為提高文件品質，我們決定採取以下措施：
- 要求開發商審查書面文件。
- 如果可能的話，及時更新文檔，前面的先。
- 建立並採用記錄 NIB 專案的標準，以便每個人都可以快速了解應描述哪些系統元素以及如何準確描述。好吧，開發合適的模板。
所有這些都有助於將文件的品質提高到一個新的水平。
至少我希望如此。
來源： www.habr.com