Google、Twitter 和 Spotify 如何建立文件文化 - DEV

許多技術問題最終會變成人的問題，缺乏良好的文件也不例外。編寫和維護文件是一種需要鼓勵和培養的習慣。不幸的事實是，如果沒有文件文化，再多的工具也無濟於事。今天，我們將看看 3 家高效能工程公司，Google、Twitter 和 Spotify，如何處理他們的技術文件並建立文件文化。

谷歌

Riona MacNamara在2016年發表了一篇精彩的演講，講述了她在谷歌改善其內部文件狀況的工作。我們強烈建議你觀看這個演講（只有30分鐘），但這裡有一些他們在2014年時面臨的問題的有趣亮點。

• 48%的谷歌工程師認為糟糕的文件是第一生產力問題
• 50%以上的SRE問題提到了文件的問題
• 文件被認為是每個人的問題，但沒有人負責的工作

每個人都感受到了不良文件的痛苦。儘管過去做了很多努力，但都沒有成功。檔案仍然分散在維基、隨機檔案中，甚至是離線的白板上。將技術寫手嵌入團隊會有一段時間的幫助，但寫手離開後，文件會迅速惡化。

那麼，是什麼讓他們開始改變現狀的呢？他們用一個叫做g3docs的系統從根本上簡化了工程師的文件。它做到了以下幾點。

• 移除決定--提出一種方法來記錄事情
• 把文件放在Markdown的原始碼旁邊，這樣工程師就可以留在他們的IDE中了
• 文件在提交時被自動渲染成漂亮的HTML頁面

在他們所做的工具工作的基礎上，該團隊還到處創造組織變革。

• 與有影響力的工程師結成聯盟，引入工具。
• 與特定的團隊合作，建立戰略整合
• 在公開場合進行釋出和迭代
• 不強迫團隊採用新的工作流程--以身作則

在g3docs被採用後，使用量增長到每月20萬+文件更新和390萬頁面瀏覽量（注意：這些數字是2016年的）。

Twitter

早在2014年，Twitter有3名技術文件寫手。在其他方面，他們的職責是協助1000多名軟體工程師編寫內部文件。同時，在Twitter，圍繞著文件的總體氛圍是不完整的、過時的，甚至是不存在的。大多數文件都在Confluence中，但也有一些是在Google Docs或READMEs中。

Simeon Franklin和Marko Gargenta有一個很棒的演講，他們討論了他們採取的策略。與谷歌類似，他們開始了改變人們對文件的看法的旅程。

他們提出了軟體工程師和測試的例子：不久前，人們還不期望軟體工程師寫測試。這種期望已經被顛覆了，今天，未經測試的程式碼是不被看好的。他們想在Twitter的內部對文件做同樣的事情。

他們的方法包括三個部分。

• 通過教育和特殊的DocDays來鼓勵文件工作
• 建立一個新的文件即程式碼的堆疊（DocBird）。
• 建立文件模板

他們組織了DocDays，這是一個單日的黑客活動，開發人員在此更新他們的文件。技術作家會在這一天提供培訓，並幫助編輯最終的文件。這些日子的更大目的是將文件寫作作為一種實踐來宣傳和規範。它建立了社群和一套共同的關於文件的期望。

為了使文件編寫更容易和標準化，他們推出了一個新的文件即程式碼的堆疊，叫做DocBird，它是一個圍繞Sphinx的定製包裝。與g3docs類似，它從源頭自動構建你的文件。它消除了 "文件在哪裡 "的問題。

最後，他們為文件建立了共享模板。這些模板有共同的部分和問題，可以被複制到專案中作為起點使用。盯著一張空白的畫布有時是開始寫作的最困難的部分。

Spotify

讓Spotify的故事變得有趣的是，他們已經在一個叫做Backstage的專案中開源了他們用於文件方法的大部分堆疊。

Backstage是Spotify眾多微服務的一個軟體目錄。它有一長串的功能和外掛，但最受歡迎的功能之一是對文件即程式碼的整合支援。

在內部，我們叫它TechDocs。到目前為止，它是Spotify使用最多的外掛--佔我們Backstage流量的20%（儘管它只是130多個外掛中的一個）。

Spotify使用Backstage的文件即程式碼的過程就像我們以前的案例研究一樣：工程師們認為第三大問題是無法找到他們工作所需的技術文件。文件分散在Confluence、Google Docs和自定義網站上，而且什麼都找不到。

Gary Niemen有一個演講，他討論了他們團隊在建立Spotify的 "文件即程式碼+"基礎設施方面的工作。他強調了一些有趣的經驗。

• 保持解決方案的簡單性--這樣它就能發揮作用
• 對工程師進行嚴格的優化
• 標準化和集中化

他們的技術寫作團隊的目標是讓工程師在1分鐘內將他們的文件從 "卡住到解開"。他們繼續朝著這個目標邁進。

從中學習什麼？

這些故事中有很多共同的主題，但這些經驗可以歸結為三個要點。

• 讓工程師的生活儘可能簡單--消除摩擦
• 對你的工具進行標準化和投資
• 通過教學和以身作則使文件成為一種期望

我們在這三個案例中所看到的，許多讀者根據經驗可能會同意，工程師不會在維基中維護文件。從你的程式碼轉移到一個單獨的系統，並且不能使用你現有的工具，這種背景轉換意味著文件會被遺忘。在這些例子中，三家公司都採用了 "文件即程式碼 "的方法，因為它使開發人員在更新文件時無障礙。

這三家公司也都在工具方面進行了大量的投資。無論你為你的文件堆疊選擇什麼（我們顯然堅信Doctave是一個優秀的解決方案），堅持下去，並確保這是技術文件的唯一地方。關於文件的位置，不應該有任何疑問。

最後，這可能是最難的部分，你需要讓文件成為工程文化的一部分。這意味著教開發人員如何寫文件，提供使用的例子和模板，組織專門針對文件的黑客日，並與你的組織中具有影響力的工程師合作以設定期望。就像今天測試如何成為大多數工程師接受的規範一樣，文件也可以。