# Solving community problems with documentation
###### 線上共筆

我在 Google 的he open source programs office，我負責 Cesar Nevarez 專案。所以我非常關心documentation。我是Technical Communication協會的榮譽會員。我運營著一個線上英語詞典。我還運營著 Study Home Appreciation Society。那邊有一些貼紙，我帶了很多。所以這就是我的偏見，對吧？我實際上是支持程式語言(pro words)的。所以今天我要和大家聊一下 Google Cesar Talks 專案，更重要的是，我們從這個專案中學到的一些open sourcedocumentation的做法。這裡有多少人曾經參與過這個專案，無論是作為一個organizations 還是一個technical writers(technical writer)？ Google Season of Ducks是由 Google 的 Sarah Maddox 和 Andrew Chen 創建的。該專案始於 2018 年，最初運作了兩年作為一個mentorship計劃。你可能已經注意到了 Season of Ducks這個名字和更大更知名的專案, Google Summer of Code.間的相似之處。所以該計劃的開始真的很像, Google Summer of Code，作為一個mentorship program，organizations 管理員將招募人們來從事technical writing program。從 2021 年到今天，新一季剛剛在上週五宣布，幾周後開放申請，這是一個資助計劃。讓我來談談這兩個計劃之間的區別。所以 Code 貢獻活動是一個mentorship program，它是關於建立community 。open source community ，吸引人們，讓學生，現在不僅僅是學生，而是open source初學者，在open source中獲得經驗。這個計劃已經進行了20 年。這是一個非常大的計劃。 Season of Ducks是一個資助計劃。我們直接給錢(financial support)，給予open source organizations 資金支持，以聘請professional technical writers，可以的話，不僅僅限於學生，來創建documentation。而且，該計劃的元目標是在open source中創建documentation的最佳實踐知識。現在已經是我們的第六年了，這是一個非常小的計劃。那麼，為什麼我們要這樣做呢？因為研究表明這是有效的。當大家加入project時，建立的政策和documentation是關鍵的決策因素。缺乏documentation是最近的開發者不使用特定Project的主要原因。在open sourceProject和企業中，具有良好documentation的人更具生產力。我知道這些幻燈片上有很多文字，也有一些鏈接。我已經在 POSTIT 日程表的演講描述中附上了一份 PDF。所以如果你想獲取它，你將能夠更容易地使用它。那麼 Google 季節的documentation流程是什麼？首先，你需要有一個問題。這是最簡單的一步。每個人都有問題。然後你需要考慮，我如何通過documentation解決這個問題？我的organizations ，我的Project，如何通過documentation解決這個問題？然後你要思考，我要如何知道它是否有效？我要查看哪些指標來判斷，我們有這個問題。現在它更好了。這些可以是定量指標(quantitative metrics)。它們可以是定性指標(qualitative metrics.)。我們希望它們不是靈性指標(spiritual metric)，就像我們不會請教Christopher Wally 一樣。人們會說，是的，它奏效了。然後你就雇傭一個technical writers來撰寫那份documentation。然後你寫一個案例研究。季節documentation的成功完成不是，我們是否撰寫了所有documentation？season of doc的成功完成是，我們是否撰寫了一個案例研究，概述了我們做了什麼，我們學到了什麼？到目前為止，我們網站上有 73 個案例研究可供 閱讀。你可以通過它們，並且或許覺得，那個問題聽起來令人感到熟悉的同時也覺得不安。也許我應該嘗試一下他們嘗試的方法。他們從中學到了什麼，我也可以從中學到什麼？所以案例研究包括這些要點。有一個Project描述，一個指向他們原始提案的鏈接。他們如何解決預算問題？他們的參與者是誰？那些來自Project的？和一名technical writers。他們的時間表是什麼，他們有多雄心勃勃？他們獲得了什麼結果？他們的指標是什麼，他們是否達到了任何指標？他們的整體分析和摘要是什麼？然後我們要求人們將它們放在附錄中。所以例如，如果他們提出了一個特別好的練習，來決定如何聘請technical writers，我們希望他們在附錄中鏈接它。所以，我說community 問題，我們正在談論很多關於documentation的事情。但實際上，什麼問題不是人們的問題？我的意思是，有什麼問題不是人們的問題呢？如果你有不滿意的用戶，如果你有不堪重擔的維護者(maintainers,)，如果你有對Project感到困惑並且難以入門的貢獻者(contributors)，你可能需要documentation。事實上，當Project就我們想要在他們的提案中創建哪些類型的documentation進行思考時，他們通常使用這個框架，這個框架是由丹妮拉·普羅奇達創建的。他在 2017 年的一次 Python 會議上談到了這個問題。這現在到處都是。像任何框架一樣，有些邊緣情況不符合這個框架。這只是一個很好的organizations 思維的方式。這些是Project想要做的documentation類型。以及他們對這些問題附加的指標，對吧？教程(Tutorials)，他們想要看到更多的訪問量，他們的Project，並且他們想要看到更少的問題。而對於如何工作，他們想要看到更多的訪問量。這件事是否做我想要的事情？而且他們想要看到更少的問題。他們想要解釋。關於世界上你需要了解的是什麼，以便使用、工作或使用這個Project？對於某些科學和技術的open sourceProject來說，這一點尤其重要。比如，如果你不理解某些數學(math)，這個Project就不適合你。但是這裡有一個你可以理解這種數學的方法。所以他們希望從不理解科學背後的人那裡獲得更多的 PR，並且希望得到更少的問題。而參考documentation，許多Project都有 API，而這些 API 沒有被很好地描述。所以他們希望有更多的覆蓋率(coverag)，對吧？讓我們確保我們對每個函數和每個我們將要使用的 API 都有覆蓋。而且他們希望得到更少的問題。因為問題會占用維護者和貢獻者的時間，並且導致維護者的不堪重擔。維護者認 為維護者不堪重擔在open source中不是問題。很棒。所以實際上，這些問題中的很多可以通過更多的人解決，對吧？更多的人來到你的Project，你就給了我們漏斗頂部(the top of the funnel)，然後happy users變成了happy contributors，變成了happy maintainers，進入了生活的另一個方面，從上面俯瞰這個Project。所以是的。更多的訪客，backstreams 減少.。所以people came and they stayed。更多的訪客，更多的用戶查看documentation。也有更多種類的人。所以這個Project向我們開放。他們的新手冊讓人們更容易入門。這意味著參加這個Project和領域中的代表不足的人在 Outreach 計劃中更成功。發現更容易入門。所以他們在我們的Project中有更多種類的人。更有知識的人。這回到了explanatory documentation。也許來到你Project的人沒有他們成功所需的技能。我們如何建立這種知識呢？更多和更有知識的人。所以這是 Kalibi Project。他們在他們的documentation中對國際化做了一個很酷的Project，使它更容易。這是他們案例研究的實際截圖，他們說，實際上，上面一行是，我把這個放在我的案例研究中。所以他們包含了這個截圖來說，是的，翻譯者實際上更快樂了，這意味著他們參與得更多。它是志願者翻譯者(volunteer translators)嗎？更多的維護者。所以 P5JS，他們制定了一個管理指南作為貢獻者documentation的一部分，但這也幫助人們理解不僅僅是一個維護者的流程，而且是一個維護者的精神。我們如何在我們的貢獻者和community 貢獻中保持信心。更多的貢獻者，對吧？所以有一個指南，我們可以發送給貢獻者，這是一個巨大的勝利。目前的貢獻者計數為 153，超過了我們的目標。而且他們也得到了更多的documentation貢獻者。有多少人認為得到優秀的documentation貢獻者很容易？更滿意和更熱情的人，對吧？人們會被燒傷的，你知道的。而且有時人們會變得憂鬱和愤世嫉俗，有時是殘酷和刻薄的。但是像這樣的Project，他們說，它激勵並動員了整個community ，並影響了其他變化，比如更新我們的管治。我本來不會預測這一點的。但是人們認為他們在community 中感到更受支持和更快樂，他們更願意承擔更多的工作。而且當人們感覺到你認真對待他們的擔憂(concerns)時，比如解決與網站有關的問題，散列錯誤，搜索時網站冰凍，這些都是次優的事情。生活品質提高。反向，為用戶和貢獻者帶來改進。你知道的，當你打掃一個地方，使它更加受歡迎，當你使它變得像燈光沒有閃爍和 HVAC 不錯時，人們就會想留下來，他們會想留下來。和更多的documentation人。所以許多參加季節的Project Docs 的Project已經發現，如果你讓人們很容易參與到documentation中來，如果你有一個旗艦Project，人們正在貢獻到documentation中，你不僅會得到你雇用的technical writers，你也會得到那些看到這種活動並想加入其中的人。所以，基本的 API，準備好的documentation貢獻者，有時technical writers開始的technical writers承包商會作為志願者繼續參與Project。更多的問人。所以一些人 問你的Project，他們不想問，他們真的不想問，因為他們害怕問。但是他們可能會在你的Project的貢獻指南中找到答案，所以這樣的Project，他們發現他們得到了更少的問題。更少的問題。那就是documentation的結果。所以，這就是我要分享的所有內容。如果你想了解更多信息，你可以在 GitHub 上找到我，你可以在 Twitter 上找到我，你可以在LinkedIn 上找到我。我很高興在這裡與大家見面，如果你有任何問題，請不要猶豫與我聯繫。感謝你的時間，謝謝。