為 MDN 網絡文檔做貢獻

MDN Web Docs 已經記錄了 Web 平台超過 12 年，現在是一個跨平台的工作，有來自谷歌、微軟和三星以及代表 Firefox 的成員的貢獻和顧問委員會。 MDN 的基礎是它是一個巨大的社區努力，網絡社區幫助創建和維護文檔。 在本文中，我將為您提供一些關於您可以幫助為 MDN 做出貢獻的地方以及具體如何做的建議。

如果您之前沒有為開源項目做出過貢獻，那麼 MDN 是一個很好的起點。 需要的技能範圍包括編輯、從英語翻譯成其他語言、創建交互式示例的 HTML 和 CSS 技能，或者對更新瀏覽器兼容性數據的瀏覽器兼容性感興趣。 您不需要做的是編寫大量代碼來貢獻。 如果您發現這些文檔很有用，這非常簡單，也是回饋社區的絕佳方式。

貢獻給文檔頁面

您可能想要貢獻的第一個地方是 MDN 文檔本身。 MDN 是一個 wiki，因此您可以登錄並開始通過更正或添加任何 CSS、HTML、JavaScript 或 MDN 涵蓋的 Web 平台的任何其他部分的文檔來提供幫助。

要開始編輯，您需要使用 GitHub 登錄。 與 wiki 一樣，頁面的任何編輯器都會被列出，此部分將使用您的 GitHub 用戶名。 如果您查看頁面底部列出的 MDN 貢獻者的任何頁面，下圖顯示了 CSS 網格佈局頁面的當前貢獻者。

你可以編輯什麼？

作為編輯，您可能會考慮修復明顯的拼寫錯誤和語法錯誤。 如果您是一名優秀的校對員和文案編輯員，那麼您很可能可以通過修復您發現的任何拼寫或其他錯誤來提高文檔的可讀性。

您可能還會發現技術錯誤，或者規格發生變化的地方以及更新或澄清有用的地方。 憑藉 MDN 涵蓋的大量 Web 平台功能和變化率，如果您發現某些東西，很容易過時 - 修復它！

您也許可以使用一些您必須添加的特定知識來添加附加信息。 例如，Eric Bailey 一直在向許多頁面添加可訪問性問題部分。 這是一項出色的工作，旨在突出我們在使用特定事物時應該考慮的事情。

您可以添加到頁面的另一個地方是添加“另請參閱”鏈接。 這些可能是指向 MDN 其他部分或外部資源的鏈接。 添加外部資源時，這些資源應該與該文檔所描述的屬性、元素或技術高度相關。 一個好的候選者將是一個演示如何使用該功能的教程，這將為搜索信息的讀者提供有價值的下一步。

如何編輯文檔？

登錄後，您將在 MDN 的頁面上看到一個編輯鏈接，單擊此鏈接將帶您進入所見即所得的編輯器以編輯內容。 您的前幾次編輯可能是很小的更改，在這種情況下，您應該能夠隨心所欲地編輯文本。 如果您正在進行大量編輯，那麼值得先查看樣式指南。 還有一個使用 WYSIWYG 編輯器的指南。

進行編輯後，您可以預覽然後發布。 在發布之前，最好解釋一下您添加的內容以及使用“修訂註釋”字段的原因。

語言翻譯

我們這些以英語為第一語言的人在網絡信息方面非常幸運，能夠以我們自己的語言獲得幾乎所有我們想要的信息。 如果您能夠將英語頁面翻譯成其他語言，那麼您可以幫助翻譯 MDN Web Docs，讓更多人可以使用所有這些信息。

如果您單擊任何頁面上的語言圖標，您可以看到該信息已被翻譯成哪些語言，並且您可以在翻譯 MDN 頁面頁面上的信息之後添加自己的翻譯。

交互式示例

MDN 上的交互式示例是您將在 MDN 的許多頁面頂部看到的示例，例如grid-area​​屬性的示例。

這些示例允許 MDN 的訪問者在 MDN 上嘗試各種 CSS 屬性值或嘗試 JavaScript 函數，而無需進入開發環境即可。 添加這些示例的項目已經進行了大約一年，您可以在將交互式示例帶到 MDN 的帖子中了解該項目和迄今為止的進展。

這些交互式示例的內容保存在交互式示例 GitHub 存儲庫中。 例如，如果您想找到 grid-area 的示例，您可以在live-examples/css-examples/grid下的那個 repo 中找到它。 在該文件夾下，您將找到兩個用於grid-area的文件，一個 HTML 和一個 CSS 文件。

網格區域.html

 <section class="example-choice-list large" data-property="grid-area"> <div class="example-choice" initial-choice="true"> <pre><code class="language-css">grid-area: a;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: b;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: c;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> </section> <div class="output large hidden"> <section class="default-example"> <div class="example-container"> <div class="transition-all">Example</div> </div> </section> </div>

grid.area.css

 .example-container { background-color: #eee; border: .75em solid; padding: .75em; display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(3, minmax(40px, auto)); grid-template-areas: "aaa" "bcc" "bcc"; grid-gap: 10px; width: 200px; } .example-container > div { background-color: rgba(0, 0, 255, 0.2); border: 3px solid blue; } example-element { background-color: rgba(255, 0, 200, 0.2); border: 3px solid rebeccapurple; }

交互式示例只是一個小演示，它使用一些標準類和 ID，以便框架可以選擇示例並使其具有交互性，其中值可以由想要快速查看它的頁面的訪問者更改作品。 要添加或編輯交互式示例，首先 fork 交互式示例存儲庫，將其克隆到您的計算機上，然後按照貢獻頁面上的說明從 npm 安裝所需的包，並能夠在本地構建和測試示例。

然後創建一個分支並編輯或創建您的新示例。 一旦您對它感到滿意，請向 Interactive Examples 存儲庫發送一個 Pull Request，要求對您的示例進行審查。 為了使示例保持一致，評論是相當挑剔的，但應該以清晰的方式指出您需要進行的更改，以便您可以更新您的示例並使其獲得批准、合併並添加到 MDN 頁面。

現在幾乎涵蓋了所有的 CSS（除了 JavaScript 示例），MDN 現在正在尋求幫助來構建 HTML 示例。 MDN Discourse 論壇上的帖子中有關於如何開始的說明。 查看該帖子，因為它提供了指向 Google 文檔的鏈接，您可以使用該鏈接來表明您正在處理特定示例，以及其他一些有用的信息。

交互式示例對於探索 Web 平台的人們非常有用，因此添加到項目中是一種極好的貢獻方式。 貢獻 CSS 或 HTML 示例需要 CSS 和 HTML 知識，以及想出清晰演示的能力。 最後一點通常是最難的部分，我創建了很多 CSS 交互示例，並且花費更多時間為每個屬性考慮最佳示例，而不是實際編寫代碼。

瀏覽器兼容數據

最近，MDN 頁面上列出的瀏覽器兼容性數據已開始通過瀏覽器兼容性項目進行更新。 本項目正在開發 JSON 格式的瀏覽器兼容性數據，它可以顯示 MDN 上的兼容性表，也可以作為其他用途的有用數據。

Browser Compatibility Data 在 GitHub 上，如果您發現頁面信息不正確或仍在使用舊表，您可以提交 Pull Request。 存儲庫包含貢獻信息，但是，最簡單的開始方法是編輯現有示例。 我最近更新了 CSS shape-outside屬性的信息。 該屬性已經有一些新格式的數據，但它不完整且不正確。

為了編輯這些數據，我首先對 Browser Compat Data 進行了 fork，這樣我就有了自己的 fork。 然後我將它克隆到我的機器上並創建了一個新分支來進行更改。

有了新分支後，我找到了shape-outside的 JSON 文件，並且能夠進行編輯。 我已經對該屬性的瀏覽器支持有了一個好主意； 當我不確定時，我還使用 shape-outside MDN 頁面上的實時示例進行測試以查看支持。 因此，進行編輯需要處理文件，檢查列出的版本號以支持該屬性並更新不正確的版本。

由於該文件是 JSON 格式，因此在任何文本編輯器中編輯都非常簡單。 .editorconfig 文件解釋了這些文檔的簡單格式規則。 此清單中還有一些有用的提示。

完成編輯後，您可以提交更改，將分支推送到 fork，然後向 Browser Compat Data 存儲庫發出拉取請求。 與實際示例一樣，審閱者很可能會對您進行一些更改。 在我的 Shapes 數據 PR 中，我在如何標記數據時遇到了一些錯誤，需要對鏈接進行一些更改。 這些很容易製作，然後我的 PR 被合併了。

開始使用

在許多情況下，您只需選擇要添加的內容並開始工作即可開始。 如果您對此有任何疑問或需要任何幫助，那麼 MDN Discourse 論壇是發帖的好地方。 MDN 是我查找信息的地方，是我發送新開發人員和經驗豐富的開發人員的地方，它的優勢在於我們都可以努力讓它變得更好。

如果您以前從未對項目提出過拉取請求，那麼在此進行第一次 PR 是一個非常友好的地方，並且正如我希望我已經展示的那樣，有一些貢獻方式根本不需要編寫任何代碼。 對於任何文檔項目來說，一個非常有價值的技能是寫作、編輯和翻譯，因為這些技能可以幫助世界各地的更多人更容易閱讀和訪問技術文檔。