編寫風格指南

通用編寫指南

目標是編寫包含讀者理解當前主題所需所有資訊的頁面。

以下小節提供了實現此目標的建議

• 考慮您的目標受眾
• 考慮編寫的三 C 原則
• 包含相關示例
• 提供描述性介紹
• 使用包容性語言
• 以 SEO 為導向進行編寫

考慮您的目標受眾

請記住您正在撰寫的內容的目標受眾。例如，一篇關於高階網路技術的頁面可能不需要像典型的網路頁面那樣詳細介紹基本網路概念。請記住這些是指導方針。其中一些提示可能不適用於所有情況。

考慮編寫的三 C 原則

良好寫作的三個 C 是清晰（Clear）、簡潔（Concise）和一致（Consistent）。

• 清晰：確保您的文字清晰簡潔。通常，使用主動語態和明確的代詞。寫短句子，每句只表達一個想法。在使用新術語之前，先定義它們，同時考慮目標受眾。
• 簡潔：編寫任何文件時，瞭解要說什麼很重要。如果您提供過多細節，頁面會變得冗長難讀，並且很少會被使用。
• 一致：確保在整個頁面以及多個頁面上使用相同的措辭。

包含相關示例

通常，新增示例或真實場景可以更好地解釋您正在撰寫的內容。這有助於讀者以更具體、更實用的方式理解概念性和程式性資訊。

您應該使用示例來澄清每個引數的用途，並澄清可能存在的任何極端情況。您還可以使用示例來演示常見任務的解決方案和可能出現問題的解決方案。

提供描述性介紹

確保第一個標題前的開頭段落充分總結了頁面將涵蓋的資訊，以及讀者在閱讀內容後可能能夠實現的目標。這樣，讀者可以快速確定該頁面是否與其關注點和預期學習成果相關。

在指南或教程中，引言段落應告知讀者將涵蓋的主題以及讀者應具備的先決知識（如果有）。開頭段落應提及正在記錄或討論的技術和/或 API，並附有相關資訊的連結，並應提供文章內容可能在哪些情況下有用的提示。

• 簡短引言示例：這個引言示例太短了。它遺漏了太多資訊，例如“描邊”文字到底是什麼意思，文字在哪裡繪製，等等。

  CanvasRenderingContext2D.strokeText() 繪製一個字串。

• 冗長引言示例：此示例的引言已更新，但現在太長了。包含了過多的細節，並且文字過於深入地描述了其他方法和屬性。相反，引言應該側重於 strokeText() 方法，並應參考描述其他細節的適當指南。

  呼叫時，Canvas 2D API 方法 CanvasRenderingContext2D.strokeText() 使用當前的畫筆顏色，描邊指定字串中的字元，從指定座標開始。在計算機圖形學術語中，“描邊”文字意味著繪製字串中字形的輪廓，而不填充每個字元的顏色。

  文字使用上下文中 font 屬性中指定的當前字型繪製。

  文字相對於指定座標的放置由上下文的 textAlign、textBaseline 和 direction 屬性決定。textAlign 控制字串相對於指定 X 座標的放置；如果值為 "center"，則字串從 x - (stringWidth / 2) 開始繪製，將指定的 X 座標放在字串的中間。如果值為 "left"，則字串從 x 的指定值開始繪製。如果 textAlign 為 "right"，則文字繪製成在指定的 X 座標處結束。

  (…)

  您可以選擇提供第四個引數，讓您指定字串的最大寬度（以畫素為單位）。如果提供此引數，文字在繪製時會被水平壓縮或縮放（或以其他方式調整）以適應該寬度空間。

  您可以呼叫 fillText() 方法來繪製填充顏色的字串字元，而不是隻繪製字元輪廓。

• 適當引言示例：以下部分為 strokeText() 方法提供了更好的概述。

  CanvasRenderingContext2D 方法 strokeText()，作為 Canvas 2D API 的一部分，描邊（繪製輪廓）指定字串中的字元，錨定在給定 X 和 Y 座標指示的位置。文字使用上下文的當前 font 繪製，並根據 textAlign、textBaseline 和 direction 屬性進行對齊和定位。

  有關更多詳細資訊和示例，請參閱繪圖圖形頁面上的 文字 部分以及我們的主要主題文章 繪製文字。

使用包容性語言

MDN 擁有廣泛而多元的受眾。我們強烈建議儘可能保持文字的包容性。以下是文件中常用術語的一些替代方案

• 避免使用 master 和 slave 術語，而是使用 main 和 replica。
• 將 whitelist 和 blacklist 替換為 allowlist 和 denylist。
• Sanity 應該替換為 coherence。
• 不要使用 dummy，而是使用 placeholder。
• 您不應該在文件中使用 crazy 和 insane 術語；但是，如果出現這種情況，請考慮使用 fantastic 代替。

在任何與性別無關的寫作中，最好使用中性語言。例如，如果您正在談論某個男性的行為，使用“他”/“他的”是沒問題的；但如果主題是任何性別的個人，那麼“他”/“他的”就不合適了。

讓我們看以下示例

• 不正確：“一個確認對話方塊詢問使用者是否希望允許網頁使用他的攝像頭。”
• 不正確：“一個確認對話方塊詢問使用者是否希望允許網頁使用她的攝像頭。”

兩種版本都具有性別特異性。為了解決這個問題，請使用中性代詞，例如

• 正確：“一個確認對話方塊詢問使用者是否希望允許網頁使用他們的攝像頭。”

另一個選擇是將使用者變為複數，例如

• 正確：“一個確認對話方塊詢問使用者是否希望允許網頁使用他們的攝像頭。”

當然，最好的解決方案是重寫並消除代詞

• 正確：“出現一個請求使用者允許訪問攝像頭的確認對話方塊。”
• 正確：“出現一個詢問使用者是否允許使用攝像頭的確認對話方塊。”

處理此問題的最後一個例子可以說更好。它不僅在語法上更正確，而且消除了處理不同語言中性別規則可能大相徑庭的一些複雜性。這種解決方案可以使讀者和翻譯人員的翻譯更容易。

使用易於理解的語言

避免使用空間和方向詞，例如“上方”、“下方”、“左側”、“右側”或“此處”。這些術語假定了一個特定的視覺佈局，這可能不適用於所有使用者。它們也可能不清楚或具有誤導性——特別是對於依賴螢幕閱讀器或閱讀翻譯內容的使用者，其中方向性語言可能模糊不清或難以準確翻譯。在響應式佈局中，內容的位置可能會根據螢幕大小而變化，這種方向性引用可能會變得不準確。這種語言可能會阻礙可訪問性，並使所有使用者更難導航或理解內容。

相反，使用描述性短語，清楚地標識所引用的部分、概念或元素。透過其標題或副標題引用部分，並透過其演示或包含的內容引用示例或程式碼片段。

例如

• 正確：“請參閱本頁面稍後的可訪問性部分。”

• 不正確：“請參閱下面的可訪問性部分。”

• 正確：“在以下程式碼示例中，我們使用 CSS 過渡來動畫一個圓形。”

• 不正確：“在下面的程式碼示例中，我們使用 CSS 過渡來動畫一個圓形。”

• 正確：“這個概念在前面題為‘建立媒體查詢’的部分中進行了解釋。”

• 不正確：“這個概念在上面一節中進行了解釋。”

此外，避免使用模糊的連結文字，如“點選此處”或“閱讀本文”。描述性連結文字為所有讀者提供了更好的上下文，並改善了輔助技術使用者的體驗。

• 正確：“瞭解有關如何排序彈性專案的更多資訊。”
• 不正確：“點選此處瞭解更多資訊。”
• 不正確：“閱讀本文瞭解更多資訊。”

透過遵循這些指南，您可以幫助 MDN 文件易於訪問、清晰並可供所有人使用，無論他們如何訪問頁面。

以 SEO 為導向進行編寫

儘管 MDN Web 文件中任何寫作的主要目標始終是解釋和介紹開放網路技術，以便開發人員能夠快速學習他們想要做的事情或找到他們需要知道的小細節以完善他們的程式碼，但重要的是他們能夠找到我們編寫的材料。我們可以透過在寫作時牢記搜尋引擎最佳化（SEO）來實現這一目標。

本節涵蓋了內容的標準做法、建議和要求，以幫助確保搜尋引擎能夠輕鬆地對我們的材料進行分類和索引，從而確保讀者能夠輕鬆找到他們所需的資訊。SEO 指南包括確保作者和編輯所處理的每個頁面都經過合理的設計、編寫和標記，以便為搜尋引擎提供正確索引文章所需的上下文和線索。

在編寫和審閱內容時，請牢記以下核對清單，以幫助確保頁面及其相鄰頁面能夠被搜尋引擎正確索引

• 確保頁面之間不過於相似：如果不同頁面的內容在文字上相似，即使它們不是同一事物，搜尋引擎也會假定這些頁面是關於同一事物的。例如，如果一個介面具有 width 和 height 屬性，那麼在文件化這兩個屬性的兩個頁面上，文字很容易驚人地相似，只是替換了幾個詞並使用了相同的示例。這使得搜尋引擎很難區分哪個是哪個，它們最終會共享頁面排名，導致兩者都比應有的更難找到。

  因此，重要的是確保每個頁面都有自己的內容。以下建議可以幫助您實現這一目標

  • 解釋更多獨特的概念：考慮用例，其中可能存在比人們想象的更多的差異。例如，在文件化 width 和 height 屬性的情況下，也許可以寫一些關於水平空間和垂直空間如何不同使用的方式，並提供關於適當概念的討論。也許您可以提及 width 在為側邊欄騰出空間方面的使用，而 height 用於處理垂直滾動或頁尾。包含有關可訪問性問題的資訊也是一個有用且重要的想法。
  • 使用不同的示例：在這些情況下，示例通常比正文文字更相似，因為示例可能一開始就使用了相似的方法或屬性（或所有），因此在重用時無需進行任何實際更改。因此，請刪除示例並編寫一個新的，或者至少提供多個示例，其中至少有一些是不同的。
  • 為示例新增描述：應包含對示例功能的概述，以及根據主題的複雜性和目標受眾，以適當的詳細程度說明其工作原理。

  避免過度相似的最簡單方法當然是，如果時間允許，從頭開始編寫每篇文章。

• 確保頁面不要太短：如果頁面上的內容過少（在 SEO 術語中稱為“瘦頁面”），搜尋引擎將無法準確（或根本無法）對這些頁面進行分類。內容過短的頁面很難被找到。作為指導原則，請確保 MDN Web 文件上的頁面長度不少於約 300 字。不要人為地增加頁面長度，但儘可能將此指南視為最低目標長度。

  這些基本指南可以幫助您建立內容充足的頁面，以便正確搜尋，而無需用不必要的文字來堆砌它們

  • 避免佔位內容（stubs）：顯然，如果文章是佔位內容或缺少內容，請新增它。我們試圖避免 MDN Web Docs 上出現完全的“佔位”頁面，儘管它們確實存在，但有很多頁面缺少大部分內容。
  • 審閱頁面結構：審閱頁面，確保其結構與其頁面型別正確對應。檢查以確保所有部分都存在並具有適當的內容。
  • 確保完整性：審閱各部分，確保沒有遺漏任何資訊。確保所有引數都已列出並解釋。確保所有異常情況都已涵蓋——這是內容特別容易缺失的地方。
  • 確保所有概念都充分闡述：快速解釋某事很容易，但要確保涵蓋所有細微之處。是否有特殊情況？是否有讀者可能需要了解的已知限制？
  • 新增示例：應提供涵蓋所有引數的示例，或者至少是初學者到中級使用者可能使用的引數（或屬性、或特性）的示例，以及任何需要額外解釋的高階示例。每個示例前面都應有一個概述，說明示例將做什麼，理解它可能需要哪些額外知識等等。示例之後（或穿插在示例片段之間）應有文字解釋程式碼如何工作。不要吝嗇示例中的細節或錯誤處理。請記住，使用者會複製並貼上您的示例以在他們自己的專案中使用，並且您的程式碼會最終用於生產站點！請參閱我們的程式碼示例指南以獲取更多有用資訊。
  • 解釋用例：如果所描述的功能有特別常見的用例，請討論它們！不要假設使用者會發現所記錄的方法可以用於解決常見的開發問題，而應實際新增一個關於該用例的部分，並附上示例和解釋示例如何工作的文字。
  • 新增影像資訊：所有影像和圖表都應包含正確的 alt 文字。此文字以及表格和其他圖表的標題都很重要，因為蜘蛛無法爬取影像，因此 alt 文字會告訴搜尋引擎爬蟲嵌入式媒體包含什麼內容。

    注意： 不建議為了操縱搜尋引擎排名而包含過多關鍵詞或與功能無關的關鍵詞；這種行為很容易被發現並受到懲罰。同樣，不要在實際頁面內新增重複的、無用的材料或關鍵詞堆，以試圖增加頁面大小和搜尋排名。這弊大於利，既損害了內容的可讀性，也損害了我們的搜尋結果。

• 關注主題內容：圍繞頁面的主題而不是特定關鍵詞撰寫內容要好得多。一個給定主題很可能包含許多關鍵詞；事實上，許多 SEO 專家會編制一個包含 5-100 個不同關鍵詞（根據長度不同，包括短尾、中尾和長尾關鍵詞）的列表，以便在文章中包含。這樣做將使您的措辭多樣化，減少重複。

編寫風格

除了用英語書寫語法正確的句子外，我們建議您遵循以下準則，以保持 MDN Web Docs 內容的一致性。

• 縮寫和首字母縮略詞
• 大寫
• 縮寫形式
• 數字和數字符號
• 複數形式
• 撇號和引號
• 逗號
• 連字元
• 拼寫
• 術語
• 語態

縮寫和首字母縮略詞

縮寫是較長單詞的縮短版本，而首字母縮略詞是使用短語中每個單詞的首字母建立的新詞。本節描述了縮寫和首字母縮略詞的指南。

• 展開：在頁面中首次提及某個術語時，請展開使用者可能不熟悉的首字母縮略詞。如有疑問，請展開該術語。更好的是，將其連結到描述該技術的文章或詞彙表條目。

  • 正確：“XUL（XML 使用者介面語言）是 Mozilla 基於 XML 的語言...”
  • 不正確：“XUL 是 Mozilla 基於 XML 的語言...”

• 大寫和句號：所有縮寫和首字母縮略詞，包括“US”和“UN”等組織，都使用全大寫並刪除句號。

  • 正確：XUL
  • 不正確：X.U.L.; Xul

• 拉丁語縮寫：您可以在括號表示式和註釋中使用常見的拉丁語縮寫（etc.，i.e.，e.g.）。在這些縮寫中使用句號，後跟逗號或其他適當的標點符號。

  • 正確：Web 瀏覽器（例如 Firefox）可以使用...
  • 不正確：Web 瀏覽器 e.g. Firefox 可以使用...
  • 不正確：Web 瀏覽器, e.g. Firefox, 可以使用...
  • 不正確：Web 瀏覽器, (eg: Firefox) 可以使用...

  在常規文字中（即，註釋或括號之外的文字），使用縮寫的英文等效詞。

  • 正確：……網頁瀏覽器等等。

  • 不正確：……網頁瀏覽器，etc.

  • 正確：像 Firefox 這樣的網頁瀏覽器可以使用...

  • 不正確：網頁瀏覽器 e.g., Firefox 可以使用...

  下表總結了拉丁語縮寫的含義和英語等效詞

  縮寫	拉丁語	英語
  cf.	confer	比較
  e.g.	exempli gratia	例如
  et al.	et alii	及其他人
  etc.	et cetera	等等，諸如此類
  i.e.	id est	也就是說，換句話說
  N.B.	nota bene	請注意
  P.S.	post scriptum	附言

  注意： 務必考慮使用拉丁文縮寫是否真正有益。其中一些使用頻率如此之低，以至於許多讀者要麼混淆其含義，要麼根本不理解。

  另外，如果您選擇使用它們，請務必正確使用。例如，請注意不要混淆“e.g.”和“i.e.”，這是一個常見的錯誤。

• 縮寫和首字母縮略詞的複數：對於縮寫和首字母縮略詞的複數，加 s。不要使用撇號。永遠不要。拜託。

  • 正確：CD-ROMs
  • 不正確：CD-ROM's

• “Versus”、“vs.”和“v.”：如果使用縮寫，“vs.”優於“v.”，並且可以在標題中使用。在文字的其他地方，請使用完整拼寫形式“versus”。

  • 正確：this vs. that
  • 不正確：this v. that
  • 正確：this versus that

大寫

在正文中使用標準英語大寫規則，並將“World Wide Web”大寫。單獨使用“web”（或作為修飾語）和“internet”時，可以使用小寫。

鍵盤鍵應使用句子式大寫，而不是全大寫。例如，“Enter”而不是“ENTER”。唯一的例外是您可以使用“ESC”來縮寫“Escape”鍵。

某些詞語應始終大寫，例如包含大寫字母的商標或源自人名的詞語（除非該詞語在程式碼中使用且程式碼語法要求小寫）。一些示例如下

• 布林（以英國數學家和邏輯學家 喬治·布林 命名）
• JavaScript（Oracle Corporation 的商標，應始終按商標形式書寫）
• Python、TypeScript、Django 以及其他程式語言和框架名稱

一些工具名稱和專案有其自己的品牌大寫規則。這些可能需要全小寫（“npm”或“webpack”）、全大寫（“UNIX”、“GNOME”、“VIM”）或混合大小寫（“TypeScript”、“macOS”或“jQuery”）的名稱。

應始終使用官方網站或文件中的品牌大寫，即使在句首也是如此。如果您對以小寫字母開頭的句子感到不適，我們建議您改寫以避免此問題。例如，您可以說“您可以使用 npm 包管理器來...”而不是“npm 允許您...”。

縮寫形式

我們的寫作風格傾向於休閒，因此如果您願意，可以隨意使用縮寫（例如，“don't”、“can't”、“shouldn't”）。

數字和數字符號

• 逗號：在常規文字中，僅在五位數及更大的數字中使用逗號。

  • 正確: 4000; 54,000
  • 不正確: 4,000; 54000

• 日期：對於日期（不包括程式碼示例中的日期），使用“January 1, 1900”格式。

  • 正確：February 24, 1906
  • 不正確：February 24th, 1906; 24 February, 1906; 24/02/1906

  或者，您可以使用 YYYY/MM/DD 格式。

  • 正確: 1906/02/24
  • 不正確: 02/24/1906; 24/02/1906; 02/24/06

• 年代：使用“1990s”格式。不要使用撇號。

  • 正確：1920s
  • 不正確：1920's

• 數字的複數：新增“s”。不要使用撇號。

  • 正確：486s
  • 不正確：486's

複數形式

使用英語風格的複數，而不是受拉丁語或希臘語影響的形式。

• 正確：syllabuses, octopuses
• 不正確：syllabi, octopi

撇號和引號

不要使用“彎引號”。在 MDN Web Docs 上，我們只使用直引號和撇號。這是因為我們需要在兩者之間選擇一個以保持一致性。如果彎引號或撇號進入程式碼片段，即使是內聯的，讀者也可能會複製和貼上它們，期望它們能夠正常工作（但它們不會）。

• 正確：請不要使用 "curly quotes."
• 不正確：請不要使用 “curly quotes.”

逗號

以下列表描述了一些我們需要注意逗號使用規則的常見情況

• 引導性從句後：引導性從句是通常位於句子開頭的從屬從句。在引導性從句後使用逗號將其與隨後的主句分開。

  • 示例 1
    • 正確：“In this example, you will learn how to use a comma.”
    • 不正確：“In this example you will learn how to use a comma.”
  • 示例 2
    • 正確：“如果您正在尋找指南，請參閱我們的寫作風格指南。”
    • 不正確：“如果您正在尋找指南請參閱我們的寫作風格指南。”
  • 示例 3
    • 正確：“在移動平臺上，您通常會得到一個數字鍵盤來輸入資料。”
    • 不正確：“在移動平臺上您通常會得到一個數字鍵盤來輸入資料。”

• 連詞前：序列逗號（也稱為“牛津逗號”）是出現在三個或更多專案系列中連詞之前的逗號。在 MDN Web Docs 上，我們使用序列逗號。逗號也分隔列表中的每個專案。

  • 正確：“我將乘坐火車、飛機和汽車。”
  • 不正確：“我將乘坐火車、飛機和汽車。”

  在包含兩個專案的列表中，不要在“and”和“or”之前使用逗號。

  • 正確：“我的狗既可愛又聰明。”
  • 不正確：“我的狗既可愛，又聰明。”

  如果“and”、“but”和“or”連線兩個獨立的從句，則在它們之前使用逗號。但是，如果句子因連詞而變得非常長或複雜，請考慮將其改寫為兩個句子。

  • 示例 1
    • 正確：“您可以執行此步驟，但您需要注意檔案設定。”
    • 不正確：“您可以執行此步驟但您需要注意檔案設定。”
  • 示例 2
    • 正確：“我父親雖然嚴厲但充滿愛意。”
    • 不正確：“我父親雖然嚴厲，但充滿愛意。”

• 在“that”和“which”之前：限制性從句對於句子的含義至關重要，不需要逗號將其與句子的其餘部分分開。限制性從句通常由“that”引入，不應在其前面加逗號。

  • 正確：“我們整理了一門課程，其中包含您實現目標所需的所有基本資訊。”
  • 不正確：“我們整理了一門課程，其中包含您實現目標所需的所有基本資訊。”

  非限制性從句提供附加資訊，對句子的含義並非必不可少。非限制性從句通常由“which”引導，其前面應加逗號。

  • 正確：“您編寫了一個策略，它是每個功能允許的來源列表。”
  • 不正確：“您編寫了一個策略它是每個功能允許的來源列表。”

• 在“such as”之前：如果“such as”是非限制性從句的一部分，並且其餘部分是獨立從句，則在“such as”之前使用逗號。

  • 正確：“Array 物件有多種運算元組的方法，例如連線、反轉和排序。”
  • 不正確：“Array 物件有多種運算元組的方法 such as joining, reversing, and sorting them.”

  以下示例展示了何時不使用逗號和“such as”。在這種情況下，包含“such as”的從句對於句子的含義至關重要。

  • 正確：“透過新增音訊和影片處理等功能，並透過 WebSockets 訪問原始資料，Web 應用程式變得越來越強大。”
  • 不正確：“透過新增音訊和影片處理等功能，並透過 WebSockets 訪問原始資料，Web 應用程式變得越來越強大。”

連字元

複合詞只有在字首的最後一個字母是母音且與詞根的第一個字母相同時才應使用連字元。

• 正確：re-elect, co-op, email
• 不正確：reelect, coop, e-mail

拼寫

使用美式英語拼寫。

一般來說，使用 Dictionary.com 的第一個條目，除非該條目被列為變體拼寫或主要用於非美式英語形式。例如，如果您查詢“behaviour”（在美式標準形式中添加了額外的 u），您會發現短語“主要用於英式英語”，後面是美式標準形式 “behavior” 的連結。不要使用變體拼寫。

• 正確：localize, behavior, color
• 不正確：localise, behaviour, colour

我們安裝了 cSpell 來捕捉拼寫錯誤。它每週執行一次，並生成一份儲存庫中的拼寫錯誤報告。您也可以使用以下命令在本地執行它

yarn lint:typos

在儲存庫中，我們維護著幾個單詞列表，位於.vscode/dictionaries，其中包含預設詞典中沒有的認可詞。如果拼寫檢查器報告的單詞有效，您可以將更多單詞新增到這些列表中。請閱讀.vscode/cspell.json以瞭解每個詞典包含的內容以及我們拼寫檢查配置的詳細資訊。

術語

以下是我們使用某些技術術語的建議

• HTML 元素：使用“元素”一詞指代 HTML 和 XML 元素，而不是“標籤”。此外，元素應使用尖括號“<>”包裹，並使用反引號 (`) 進行樣式設定。例如，在反引號內使用 <input> 將其樣式化為 <input>，這是預期的。

  • 正確：<span> 元素
  • 不正確：span 標籤

  在 MDN 上，您可以在 HTMLElement 宏中選擇性地指定 HTML 元素，該宏將對元素進行樣式設定，新增尖括號“<>”，並新增指向其參考頁面的連結。

  • 使用反引號：<span>
  • 使用宏：<span>（Markdown 原始碼：{{HTMLElement("span")}}）

• 引數與實參：MDN Web Docs 中首選的術語是 parameters。請儘可能避免使用“arguments”一詞以保持一致性。

• 使用者介面操作：在任務序列中，使用祈使語氣描述使用者介面操作。透過其標籤和型別標識使用者介面元素。

  • 正確：“點選編輯按鈕。”
  • 不正確：“點選編輯。”

語態

雖然主動語態是首選，但被動語態也是可以接受的，因為我們的內容具有非正式的風格。但請儘量保持一致。

頁面元件

本節列出了每個頁面的不同部分（例如標題、註釋、連結和示例）應遵循的指南。

• 程式碼示例
• 交叉引用（連結）
• 外部連結
• 縮短的 URL（短連結）
• 標題級別
• 影像及其他媒體
• 列表
• 另請參閱部分
• 子頁面
• 短連結（slug）
• 標題

程式碼示例

MDN Web 文件中的一個頁面可以包含多個程式碼示例。以下列表提供了為 MDN Web 文件編寫程式碼示例時的一些推薦做法

• 每段示例程式碼應包括
  • 標題：一個簡短的 ### (<h3>) 標題，描述透過程式碼示例演示的場景。例如，“使用偏移列印”和“恢復到上一層的樣式”。
  • 描述：在示例程式碼之前提供一個簡短的描述，說明您希望讀者注意的示例具體內容。例如，“在以下示例中，CSS 中定義了兩個級聯層：base 和 special。”
  • 結果解釋：在示例程式碼之後提供解釋，描述結果以及程式碼如何工作。
• 通常，程式碼示例不僅應演示該功能的語法和用法，還應強調 Web 開發人員可能希望或需要使用該目的和情況。
• 如果您正在處理一段大型示例程式碼，將其分解為更小的邏輯部分以便單獨描述可能更合理。
• 新增即時示例時，瞭解所有示例中相同型別（HTML、CSS 和 JavaScript）的程式碼塊在執行示例之前會連線起來是很有幫助的。這使您可以將程式碼分解為多個片段，每個片段可以選擇有自己的描述、標題等。這使得文件化程式碼變得極其強大和靈活。

要了解如何為 MDN Web Docs 樣式化或格式化程式碼示例，請參閱我們的程式碼示例樣式指南。

交叉引用（連結）

在 MDN 上透過標題引用另一個頁面或頁面的一部分時，連結文字應遵循句子式大小寫（與頁面或部分標題匹配）。即使連結文字與連結頁面的標題或部分標題不同（可能是頁面或部分標題中使用的字母大小寫不正確），連結文字也應使用句子式大小寫。連結文本週圍不要使用引號。要透過標題引用 MDN 上的頁面，請使用以下樣式

• 正確：“請參閱彈性專案排序指南。”
• 不正確：“請參閱“彈性專案排序”指南。”

連結到頁面內的部分時，請遵循一致的風格

• 正確：“有關更多資訊，請參閱《記憶體管理》指南中的JavaScript 中的分配部分。”

如果您要連結到的部分在同一頁面上，您可以使用描述性短語提示該部分的位置。

• 正確：“本概念將在本文件的可訪問性部分詳細描述。”
• 不正確：“本概念將在下面的可訪問性部分詳細描述。”

在 MDN 上，另一種連結到參考頁面的方法是使用宏。這些宏在常用宏頁面上進行了描述。例如，要連結到 HTML 元素的參考頁面，請使用 HTMLElement 宏；要連結到 CSS 屬性的參考頁面，請使用 CSSxRef 宏。

我們遵循類似的交叉引用指南，在參考頁面、詞彙表頁面和指南的末尾的另請參閱部分。

外部連結

MDN Web 文件允許在特定情況下使用外部連結。請使用本節中描述的指南來決定是否可以在 MDN Web 文件中包含外部連結。如果不遵循這些指南，新增外部連結的拉取請求將被拒絕。

如果您正在考慮向 MDN 的學習 Web 開發內容新增外部連結，請同時閱讀學習 Web 開發編寫指南 > 合作伙伴連結和嵌入。

通常，如果您正在考慮新增外部連結，您需要確保以下風險最小

• 失效或過時的連結
• 出現認可跡象，特別是商業產品或服務
• 試圖利用 MDN Web 文件分發垃圾郵件
• 模糊連結目標的短連結

• 好的外部連結：好的外部連結將讀者引導至相關、持久且廣受信賴的資源。您應優先新增指向以下外部內容的連結

  • 獨特或不可或缺（例如，IETF RFC）
  • 歸因、引用或致謝所必需（例如，作為知識共享署名的一部分）
  • 與在 MDN Web Docs 本身中包含此類內容相比，更可能針對該主題進行維護（例如，供應商的發行說明）
  • 開源或社群驅動，如 MDN Web Docs 本身

• 不良外部連結：不良外部連結缺乏相關性、可維護性、可訪問性，或以其他方式對讀者設定障礙。避免新增指向以下外部內容的連結

  • 通用或不具體（例如，供應商主頁，而不是相關文件）
  • 短暫或未維護（例如，一次性公告）
  • 自連結或自推廣（例如，作者在 MDN Web Docs 之外的作品）
  • 需要付費（例如，超出業餘愛好者、學生或低收入國家讀者能力的昂貴課程）
  • 無法訪問（例如，沒有字幕的影片）

• 自推廣或垃圾郵件連結：雖然個人部落格文章、會議演講或 GitHub 儲存庫具有價值，但連結到您自己的資源可能會產生利益衝突的表象。在連結到您有業務或個人關係的資源之前，請三思。

  注意： 如果您與連結目標存在業務或個人關係，您必須在拉取請求中披露該關係。未能這樣做可能會危及您繼續參與 MDN Web 文件。

  有時此類連結是相關且適當的。例如，如果您是某個規範的編輯，並且正在為與該規範相關的文件做出貢獻，那麼連結到該規範是預期且可接受的。但您必須披露您與連結之間的關係。

縮短的 URL（短連結）

URL 縮短器（例如 TinyURL 或 Bitly）非常適合將長連結縮短為短小、易於記憶的 URL（也稱為“短連結”）。然而，它們也模糊了 URL 的目的地。此外，對於某些縮短器，目的地可以在建立後更改，此功能可用於惡意目的。

不要使用透過第三方（使用者可生成）URL 縮短器建立的連結。例如，如果 https://myshort.link/foobar 是由隨機使用者生成的短 URL，並重定向到 https://example.com/somelongURL/details/show?page_id=foobar，則使用較長的 example.com URL。

另一方面，鼓勵使用由維護目標 URL 的組織維護的第一方縮短器。https://bugzil.la 由 Mozilla 擁有和運營，是一個 URL 縮短器，重定向到 https://bugzilla.mozilla.org/，後者也是 Mozilla 擁有的域名。在這種情況下，請使用較短的 URL。例如，使用 https://bugzil.la/1682349 而不是 https://bugzilla.mozilla.org/show_bug.cgi?id=1682349。

標題級別

當新段落開始一個新部分時，應新增標題。按遞減順序使用這些 markdown 標題級別，不要跳過級別：##，然後是 ###，然後是 ####；它們分別轉換為 HTML 標題標籤 <h2>、<h3> 和 <h4> 標籤。

## 是允許的最高級別，因為 # 保留用於頁面標題。我們建議標題級別不要超過三級。如果您覺得需要新增第四級標題，請考慮將文章分解為幾個帶有登陸頁面的較小文章。或者，考慮將資訊作為專案符號列表呈現，以避免使用四級標題。

在建立小節標題時，請記住以下注意事項

• 不要建立單個子節。 不要將一個主題細分為一個子主題。要麼是兩個或更多子標題，要麼一個都沒有。
• 不要在標題中使用內聯樣式、類或宏。 但是，您可以使用反引號來指示程式碼術語（例如，“使用 FooBar 介面”）。
• 不要建立“撞頭”標題。 它們是指緊跟在子標題之後的標題，它們之間沒有內容文字。這看起來不好，並且使讀者在外部部分的開頭沒有任何解釋性文字。

影像及其他媒體

如果您在頁面中包含影像或其他媒體，請遵循以下指南

• 確保媒體許可證允許您使用它們。儘量使用具有非常寬鬆的許可證（例如 CC0）或至少與我們通用內容許可證 (知識共享署名-相同方式共享許可證 (CC-BY-SA)) 相容的媒體。
• 對於影像，請透過 https://tinypng.com 或 https://imageoptim.com 執行它們以減小頁面重量。
• 對於 SVG，請透過 SVGOMG 執行程式碼，並確保 SVG 檔案末尾有一個空行。
• 每張圖片都必須包含描述性 alt 文字。

列表

列表應在所有頁面上保持一致的格式和結構。單個列表項應使用適當的標點符號書寫，無論列表格式如何。但是，根據您正在建立的列表型別，您需要調整您的寫作，如下面幾節所述。在這兩種情況下，都應包含一個引導句來描述列表中的資訊。

• 專案符號列表：專案符號列表應用於將相關的簡潔資訊分組。列表中的每個專案應遵循相似的句子結構。專案符號列表中的句子和短語（即，缺少動詞或主語或兩者兼有的句子片段）應包含標準標點符號——句子以句號結尾，短語則不以句號結尾。

  如果列表項中有多個句子，則每個句子末尾必須出現句號，包括該項的最後一個句子，就像段落中預期的一樣。這是一個正確結構的專案符號列表的示例

  在這個例子中，我們應該包含

  • 一個條件，並附有簡要解釋。
  • 一個類似的條件，並附有簡要解釋。
  • 另一個條件，並附有進一步解釋。

  請注意，相同的句子結構在每個專案符號之間重複。在此示例中，每個專案符號都說明了一個條件，後跟逗號和簡要解釋，並且列表中的每個專案都以句號結尾。

  如果列表項包含不完整的句子，則末尾不需要句號。例如

  以下與顏色相關的屬性在此場景中將很有幫助

  • propertyA: 設定背景顏色
  • propertyB: 為文字新增陰影

  如果一個或多個列表項是完整的句子，則在每個列表項之後使用句號，即使列表項包含三個或更少的單詞。但是，儘可能地，所有列表項遵循相同的結構；確保所有列表項都是完整的句子或短語。

• 編號列表：編號列表主要用於列舉一組指令中的步驟。由於指令可能很複雜，因此清晰度至關重要，特別是當每個列表項中的文字很長時。與專案符號列表一樣，遵循標準標點符號用法。這是一個正確結構的編號列表的示例

  為了正確構建編號列表，您應該

  1. 以標題或簡短段落開頭，以介紹說明。在開始說明之前，向用戶提供上下文很重要。
  2. 開始建立您的說明，並將每個步驟儲存在其自己的編號項中。您的說明可能非常廣泛，因此清晰書寫和使用正確的標點符號非常重要。
  3. 完成說明後，在編號列表後附上一個簡短的總結或解釋，說明完成後的預期結果。

  以下是為前面列表編寫結束語的示例

  我們建立了一個簡短的編號列表，提供了生成格式正確的編號列表的指導步驟。

  請注意，編號列表中的專案讀起來像短段落。由於編號列表通常用於指導目的或引導某人完成有序過程，因此請確保每個專案都重點突出：每個步驟一個編號專案。

另請參閱部分

MDN Web Docs 上的大多數指南、參考頁面甚至詞彙表頁面都在文章末尾包含一個“另請參閱”部分。本節包含 MDN 內部相關主題的交叉引用，有時還包含指向相關外部文章的連結。例如，這是 @layer 頁面的另請參閱部分。

通常，“另請參閱”部分中的連結以專案符號列表格式呈現，列表中的每個專案都是一個短語。然而，在 MDN 的學習 Web 開發部分，“另請參閱”部分遵循定義列表格式。

為了保持 MDN Web Docs 的一致性，在新增或更新“另請參閱”部分時，請牢記以下指南。

連結文字

• 連結文字應與連結頁面的標題或部分標題相同。例如，連結到此 ARIA 頁面（頁面標題為“ARIA states and properties”）的連結文字將是
  • 正確：ARIA states and properties
• 即使連結文字與連結頁面的標題或部分標題不同，也應使用句子大小寫。頁面或部分標題中使用的字母大小寫可能不正確。例如，指向怪異模式頁面的連結文字（正確句子大小寫）將是
  • 正確：Quirks mode
• 對於外部連結，即使目標文章頁面的大小寫不同，也請使用句子大小寫。這是為了確保 MDN Web Docs 的一致性。書籍名稱除外。
• 在 MDN 上，您可以選擇使用宏連結到頁面，如常用宏頁面上的連結到參考頁面部分所述。使用宏將為連結文字中的關鍵字新增程式碼格式，如下一個示例所示。
• 連結列表項開頭不需要冠詞（“A”、“An”、“The”）。列表項末尾不需要標點符號，因為它始終是一個術語或短語。
  • 正確：revert-layer
  • 不正確：The revert-layer keyword.
  • 正確：HTML DOM API
  • 不正確：The HTML DOM API
• 如前面的示例所示，使用反引號（`）為連結文字中的關鍵字和字面量新增程式碼格式，即使該格式未在頁面和部分標題中使用。例如，對於頁面標題“Array() constructor”，連結文字將是 Array() constructor。

描述性文字

• 圍繞連結的描述性文字應保持最少。如果需要描述，請在連結文字和冒號後新增。描述應措辭為短語，不帶結尾標點符號。所有連結文字應置於開頭，以方便快速瀏覽連結列表。
  • 正確：:checked, :indeterminate: 用於樣式化複選框的 CSS 選擇器
• 在系列中最後一個專案之前不要使用連詞“and”。
  • 正確：background-color, border-color, color, caret-color, column-rule-color, outline-color, text-decoration-color, text-emphasis-color, text-shadow: 其他與顏色相關的屬性
• 對於外部連結，在可行和適當的情況下，應儘可能註明來源網站和出版或最後更新年份（在括號中）。提前提供這些資訊可以使讀者清楚地瞭解點選連結後將到達的目的地。出版或最後更新日期有助於讀者評估連結文章的相關性，也有助於 MDN 維護人員審查長時間未更新的文章連結。例如，如果您提供維基百科文章的連結，則可以忽略出版/更新日期。以下列表項是“另請參閱”部分中新增指向 Top-level await 外部文章的連結的示例，以及來源和年份資訊
  • 正確：v8.dev 上的頂層 await (2019)
• 對於書籍的外部連結，您還可以提供作者姓名。一些示例列在延伸閱讀部分。請不要為您可能連結的部落格文章或 GitHub 儲存庫新增作者姓名。

連結順序

• 按以下順序列出指向 MDN 頁面的連結：首先是參考頁面，然後是相關指南和教程頁面的連結。此建議順序主要是為了幫助列表中的專案易於掃描。
• 如果列表是內部連結和外部連結的混合，請首先列出內部連結，然後是外部連結。
• 在內部和外部連結的每個組中，遵循字母順序或從簡單到高階的順序，以對上下文最有意義的方式。

子頁面

當您需要新增有關某個主題或主題領域的文章時，通常會透過建立登陸頁面，然後為每個單獨的文章新增子頁面來實現。登陸頁面應以一兩個段落描述該主題或技術開頭，然後提供子頁面列表，並附上每個頁面的描述。您可以使用我們建立的一些宏將頁面自動插入到列表中。

例如，考慮JavaScript指南，其結構如下

• JavaScript/Guide – 主要目錄頁面
• JavaScript/Guide/JavaScript 概述
• JavaScript/Guide/函式
• JavaScript/Guide/物件模型詳情

儘量避免將您的文章放在層次結構的頂部，這會減慢網站速度，並降低搜尋和網站導航的效率。

短連結（slug）

頁面標題顯示在頁面頂部，可能與頁面“slug”（URL 中 <locale>/docs/ 後面的部分）不同。在定義 slug 時，請牢記以下準則

• 短連結應該保持簡短。建立新的層級時，新層級在短連結中的組成部分應該只有一兩個單詞。
• 短連結應使用下劃線分隔多片語件，例如 /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax 中的 Basic_HTML_syntax。
• 在短連結中，每個元件也應遵循句子式大小寫，例如前面示例中的 Basic_HTML_syntax。

標題

頁面標題用於搜尋結果，也用於在頁面頂部的麵包屑列表中構建頁面層次結構。頁面標題可能與頁面“短連結”不同，如短連結部分所述。

撰寫標題時，請牢記以下準則

• 大寫風格：在 MDN Web Docs 上，頁面標題和部分標題應使用句子式大寫（只大寫第一個單詞和專有名詞），而不是標題式大寫

  • 正確：“A new method for creating JavaScript rollovers”
  • 不正確：“A New Method for Creating JavaScript Rollovers”

  我們有許多舊頁面是在此樣式規則制定之前編寫的。如果您願意，請隨意根據需要更新它們。我們正在逐步處理它們。

• 通用指南：決定要記錄什麼以及如何組織內容是寫作的第一步。編寫目錄可以幫助您決定如何組織資訊。先涵蓋簡單的概念，然後轉向更復雜和高階的概念。先涵蓋概念性資訊，然後轉向以行動為導向的主題。

  編寫頁面和部分或小節標題時，請牢記以下準則

  • 從高到低：如標題級別部分所述，從高 ## 到低 ####，不要跳過級別。使用更高級別的標題表示更廣泛的介紹性標題，並隨著向更低級別標題的進展使用更具體的標題。
  • 邏輯分組：確保所有相關的子節都在一個更高級別的標題下邏輯分組。命名各個部分的標題可以幫助您完成此練習。
  • 保持標題簡短：較短的標題更容易在文字和目錄中掃描。
  • 保持標題具體：使用標題來傳達該部分將涵蓋的具體資訊。例如，對於介紹 HTML 元素的部分，使用標題“HTML 元素”而不是“介紹”或“概述”。
  • 保持標題集中：使用標題傳達一個目標——一個將在該部分中涵蓋的單一思想或概念。為此，儘可能地，儘量不要在標題中使用連詞“and”。
  • 使用平行結構：在同一標題級別使用相似的語言。例如，如果 ### 標題級別標題使用動名詞（即以“-ing”結尾的詞語，例如“Installing”），那麼請嘗試在該標題級別使用動名詞編寫所有標題。如果標題以祈使動詞開頭，例如“Use”、“Configure”，那麼請在該標題級別以祈使動詞開頭編寫所有標題。
  • 避免在低階標題中出現通用術語：不要在低階標題中重複高階標題中的文字。例如，在名為“逗號”的部分中，將子節標題命名為“介紹性從句之後”而不是“介紹性從句之後的逗號”。
  • 不要以冠詞開頭：避免標題以冠詞“a”、“an”或“the”開頭。
  • 新增引導資訊：在標題之後，新增一些介紹性文字來解釋該部分將涵蓋的內容。

另見

• 編寫程式碼示例的指南
• 編寫 HTML 程式碼示例的指南
• 編寫 CSS 程式碼示例的指南
• 編寫 JavaScript 程式碼示例的指南
• 編寫 shell 提示符程式碼示例的指南

延伸閱讀

其他樣式指南

如果您對本指南未涵蓋的用法和樣式有疑問，我們建議參考 Microsoft 寫作風格指南 或 芝加哥風格手冊。

語言、語法和拼寫

如果您有興趣提高寫作和編輯技能，以下資源可能會有所幫助。

• brians.wsu.edu 上的常見英語用法錯誤
• alt-usage-english.org 上的英語語法常見問題
• english.stackexchange.com 上的英語語言和用法：英語語言用法問答網站
• google.com/books 上的《Merriam-Webster's Concise Dictionary of English Usage》（2002 年出版）：學術但使用者友好的循證建議；非常適合非母語人士，特別是介詞用法
• harpercollins.com 上的 William Zinsser 的《On Writing Well》（2016 年出版）
• google.com/books 上的 Joseph Williams 和 Gregory Colomb 的《Style: Lessons in Clarity and Grace》（2019 年出版）