WordPress 貢獻者尋求贊助以改進 Gutenberg 開發人員文檔

WordPress 開發人員 Milana Cap 和 Jonathan Bossenger 開始籌款以改進 Gutenberg 開發人員文檔。 談話開始於昨天，當 Cap 發布推文時，當公司僱用全職貢獻者在 WordPress 上工作時，文檔經常被忽視。

“當你的社區無法學習你的軟件時，你就沒有貢獻者了，”Cap 說。 “對於開源軟件項目來說，文檔和教程比人們意識到的要重要得多。”

Cap 第一次開始要求提供 Gutenberg 文檔是在 2017 年巴黎的社區峰會上。從那時起，她一直試圖將社區的注意力引向它。

“開發人員的塊編輯器文檔中有很多漏洞，但最明顯的是如何開始，”Cap 說。 “開發人員文檔的開頭並沒有說明入門。 “它只說明了你可以用一個塊做什麼，而不是_how_。 初級開發人員、純 PHP 開發人員以及該文檔所針對的任何人，不知道塊代碼的外觀、放置位置、如何包含它等，更不用說如何使用自定義組件構建自定義塊和設置。”

記錄塊編輯器的部分挑戰在於它正在積極開發中。 Gutenberg 插件不斷地進行增強和改進，跟踪核心中當前可用或不可用的內容並不總是那麼容易。 由於 WordPress 即將引入塊目錄搜索，現在是正式化塊創建文檔的好時機。

“代碼示例在整個文檔中都出現了驚人的缺失，”Cap 說。 “最基本的例子是存在的，但缺少如何實際構建可用的東西。 因此，在第一頁上，我們被發送到一個教程，但該教程並未針對以前從未構建過塊的人進行優化。 跟隨它，我已經並且將無法構建塊。”

Marcus Kazmierczak 和一個文檔貢獻者團隊正在嘗試重建官方塊編輯器手冊中的教程。 一個 GitHub 問題專注於解決當前開發人員文檔中的差距，這是一個積極討論的地方，該問題是關於為新阻礙開發的人重寫文檔的最佳方法的。

“這是一個非常好的開始，但仍有許多工作要做，”Cap 說。 “完整的文檔是由了解和理解 React 和 Gutenberg 但被‘知識詛咒’的人編寫的。 他們沒有太多時間花在了解其他人不知道多少以及應該編寫哪些詳細文檔上。 老實說，我認為他們不應該把時間花在這上面。 我們有一個文檔團隊，我們願意加入，但某種橋樑是必要的。”

Gutenberg 開發者文檔的問題：對新手不友好

“我在塊編輯器文檔中看到的'問題'是，與其他 WordPress 文檔不同，它是為有經驗的 JavaScript 開發人員編寫的，而不是針對初學者，”Bossenger 說。 “我還應該指出，這絕不是對那些將當前文檔放在一起的人的看法，我感謝他們迄今為止所做的所有工作，只是非常需要審查和一些改進。 ”

Bossenger 過去曾表示，WordPress 讓任何對 PHP 知識有限的人都​​可以非常輕鬆地使用操作和過濾鉤子快速構建插件或主題。 查看代碼並理解它應該做什麼很容易。

“現代 JavaScript，特別是 React，是一種非常不同的魚，”Bossenger 說。 “它需要更深入地了解 React 的工作原理，包括新的術語和實踐。 現代 JavaScript 也可能非常令人困惑，特別是如果這是您第一次看到箭頭函數或不那麼冗長的 if 語句之類的東西。

“如果您在 WordPress 中最接近使用 JavaScript 的一直是使用 jQuery，那麼切換到基於 React 的 Gutenberg 開發仍然需要您學習一些知識。”

Bossenger 在為編輯器構建任何東西之前學習了兩門課程，一門關於 React，一門關於 Gutenberg，他說當前的 Block Editor 手冊不是為沒有 React 和現代 JavaScript 經驗的開發人員編寫的。 他認為它需要重組以更好地解釋新概念並適應新人更容易消費的模式。 他以 Plugin Developer 手冊為例，其中章節遵循一種結構並使用更像教科書的術語，慢慢地向讀者介紹新概念。

“我認為，對於沒有插件或 PHP 知識的人來說，擁有這本手冊和谷歌，很可能構建一個簡單的插件來很快滿足他們的特定要求，”Bossenger 說。 “目前區塊編輯器手冊不利於這一點。”

Bossenger 對當前文檔的看法並不孤單。 Delicious Brains 的 Peter Tasker 最近發布了關於創建自定義 Gutenberg 塊的教程。 即使在過去一年全職使用 React 之後，他發現官方的塊編輯器文檔“有點到處都是”並且難以解析。

在 Cap 評論缺乏贊助全職文檔工作的公司之後，Bossenger 試水了一條推文，詢問他們兩人是否能夠籌集資金來改進 Gutenberg 文檔。

“就像塊編輯團隊（和任何其他製作團隊）一樣，文檔團隊人手不足，”Cap 說。 “我們不能讓少數成員先學習然後編寫有關使用塊編輯器進行開發的文檔。 這是我發推文的主要原因。 你會看到贊助的貢獻者遍布核心，但不是在文檔中，我敢說兩者同樣重要。”

在啟動他們的籌款活動之前，Cap 和 Bossenger 計劃檢查現有的文檔，找出明顯的漏洞，並找出對於那些剛開始為塊編輯器開發的人來說仍然沒有答案的問題。

“一旦我們制定了計劃，我們就可以預測每個部分需要多少時間，”她說。 “有了這個計劃，我們將尋找贊助商。 我認為在此之前會有捐贈的選擇，但目前還不確定。”

塊是 WordPress 開發的新前沿。 為初學者投資可靠的文檔和教程可能會對擴展區塊生態系統產生重大影響。 這也間接地使用戶受益，因為他們最終在自定義 WordPress 網站時可以選擇更多樣化的塊目錄。

Bossenger 和 Cap 目前正在為文檔制定計劃，然後宣布他們的籌款活動。 與此同時，任何想為改進區塊創建文檔做出貢獻的人都可以加入 GitHub 討論。