From 01d82319d26f908e24379d8c04acd8c99e498a2c Mon Sep 17 00:00:00 2001 From: t7yang Date: Mon, 3 May 2021 01:26:21 +0800 Subject: Update /mdn/guidelines/writing_style_guide, zh-TW --- .../mdn/guidelines/writing_style_guide/index.html | 691 +++++++++++---------- 1 file changed, 372 insertions(+), 319 deletions(-) (limited to 'files/zh-tw') diff --git a/files/zh-tw/mdn/guidelines/writing_style_guide/index.html b/files/zh-tw/mdn/guidelines/writing_style_guide/index.html index c9ee99400a..cc90ee9ab4 100644 --- a/files/zh-tw/mdn/guidelines/writing_style_guide/index.html +++ b/files/zh-tw/mdn/guidelines/writing_style_guide/index.html @@ -1,181 +1,316 @@ --- -title: MDN 風格指南 +title: 寫作風格指南 slug: MDN/Guidelines/Writing_style_guide -translation_of: MDN/Guidelines/Writing_style_guide +tags: + - 文件 + - 指南 + - 指導方針 + - MDN Web 文件 + - MDN 風格指南 + - 風格指南 + - 寫作風格指南 + - Documentation + - Guide + - Guidelines + - MDN + - MDN Meta + - MDN Web Docs + - MDN style guide + - Style guide + - Writing style guide ---
{{MDNSidebar}}
-

為了讓文檔更加組織化、標準化而易於閱讀，MDN 風格指南描述了文本的組織方式、拼寫和格式等問題。這些規則只是指導方針而非強制規定。與格式相比，我們對內容更感興趣，因此在你做貢獻之前，大可不必因為沒有學習本指南而感到驚訝或沮喪，只管放手去做便是。勤勞的志願者們會編輯你的工作以符合本指南。

+

為了讓文件更加組織化、標準化而易於閱讀，MDN 風格指南描述了文件的組織方式、拼寫、格式等問題。這些規則只是指導方針而非強制規定。與格式相比，我們對內容更感興趣，因此不用覺得在開始貢獻之前有被迫要學習這些指南的壓力。若之後有其他支援者修改了你的內容以便讓它符合這些指南，你也不需要因此而感到沮喪或驚訝。

-

如果你在尋找頁面應當如何結構化的具體方式，參見 MDN 頁面配置指南。

+

在語言方面，本指南主要適用於英語文件，其它語言可擁有（且歡迎建立）自己的風格指南。它們會以當地語系團隊頁面的子頁面發佈。

-

在語言方面，本指南主要適用於英語文檔，其它語言可擁有（且歡迎創建）自己的風格指南。它們應作為當地語系化團隊頁面的子頁面發佈。

- -

有關 MDN 以外網站內容的風格標準，請參考 Mozilla 風格指南。

- -

基礎

+

基礎

維持整份文件的一致性是各大文件發表風格指南的基礎。以下段落將會列出這些基礎概念來協助您。

-

頁面標題

+

頁面標題

-

頁面標題會展示於搜索結果中，也可用於在頂部的麵包屑導航列中的層次結構以建構頁面。頁面標題可以與頁面“縮略名”不同。縮略名會出現在“<locale>/docs/”後，是頁面URL的一部分。

+

頁面標題會展示於搜索結果，也可用於在頂部的麵包屑導覽列中的層次結構以建構頁面。網頁標題（既顯示在頁面頂端及搜尋結果）也會因頁面的「路徑」而異，這些路徑就是組成頁面網址的一部分—— 「<locale>/docs/」 。

-

標題與頁首的大小寫

+

標題與頁首的大小寫

-

頁面標題與章節標題應使用一般句子的大小寫形式（只大寫句首字母和專有名詞）， 而非新聞式標題。

+

頁面標題與章節標題應使用一般句子的大小寫形式（只對句首字母和專有名詞大寫），而非新聞式標題：

+
  • 正確：“A new method for creating JavaScript rollovers”
    • +
  • 錯誤：“A New Method for Creating JavaScript Rollovers”
    • + -

    有些舊的頁面編寫於本樣式規則定版之前。若你願意，可隨時更新它們。我們會逐漸完善它們。

    +

    有些舊的頁面編寫於本樣式規則定版之前。若你願意，可隨時更新它們。我們會逐漸完善它們。

    -

    選擇標題與簡述

    +

    選擇標題與路徑

    -

    頁面縮略名應保持簡短；當創建新的層級時， 該層次的縮略名通常應只由一兩個單詞組成。

    +

    頁面路徑應保持簡短。當建立新的層級時，該層級的路徑應只由一兩個單詞組成。

    至於頁面標題，只要在合理範圍內，長度可以隨意，不過它應當是描述性的。

    -

    創建新子樹

    +

    建立新的子目錄

    -

    當你需要添加關於某個主題或主題範圍的文章時，一般可以創建一個登陸頁面，然後為這些文章分別添加子頁面。登陸頁面應當以一兩段對該主題或技術的描述開頭，接著提供一個子頁面的清單，並對每個子頁面做簡短的描述。你可以用一些我們創建的巨集來將頁面自動插入到該清單中。

    +

    當你需要加入關於某個主題或主題範圍的文章時，一般可以建立一個目錄頁面，然後為這些文章分別加入子頁面。目錄頁面應當以一兩段對該主題或技術的描述開頭，接著提供一個子頁面的清單，並對每個子頁面做簡短的描述。你可以用一些我們建立的巨集來將頁面自動插入到該清單中。

    以 JavaScript 指南為例，它的結構如下：

    -

    請儘量避免將你的文章放在頂層，不然會拖慢網站的下載速度，降低網站導航和搜索的效率。

    +

    請儘量避免將你的文章放在頂層，不然會拖慢網站的下載速度，降低網站導覽和搜索的效率。

    + +

    一般文章內容指導方針

    + +

    任何文件的篇幅都應該適可而止。如果你侃侃而談或提供過多的細節，文章會變得乏味且鮮少被閱讀。文章內容涵蓋恰當的篇幅有許多好處，其中就包含：讓讀者找到他們真正想要的資訊、提供搜尋引擎足夠好的素材以便用於分析及評價文章的內容。

    + +

    本文只針對前者（提供讀者需要的資訊）進行說明。對於如何確保文章恰當的被搜尋引擎分類及評價，請移步到 MDN 如何針對 SEO 進行寫作。

    + +

    寫作的目標是要讓讀者取得所有必要資訊的同時又不會陷入太多的細節中。以下是這個主題的相關建議。

    + +

    考量讀者想要的

    + +

    要知道這些僅僅只是建議。某些建議並非適用於任何場景。時時刻刻考量讀者想要什麼。譬如，有關網路技術的進階文章就不需要講述太多有關網路基礎的觀念。

    + +

    提供有用的概述

    + +

    如果文章可能涵蓋讀者有興趣的內容，確保文章的概述——開頭的段落或是第一個標題後的段落——能夠提供讀者足夠的資訊。

    + +

    對於指南或是教學類型的內容，概述應該要能夠涵蓋讀者須知的主題且他們應先具備的知識；若有需要。同時也必須提到哪些已經被文件化或經討論的技術或 API 並以連結的方式提供相關的資訊，也別忘了給予文章內容中有幫助的提示。

    + +
    範例：過於簡短！
    + +

    這個範例就過於簡短。它缺乏太多資訊了，譬如，所謂的「 stroke 」 文字到底是什麼意思、文字又會被繪製在哪裡等。

    + +
    +

    CanvasRenderingContext2D.strokeText() draws a string.

    +
    + +
    範例：過於冗長！
    + +

    更新後的概述反而有過於冗長的問題。涵蓋了太多的資訊了，而且用來描述其他方法以及屬性的篇幅過於龐大。

    + +

    反之，概述應該著重在 strokeText() 方法本身，在輔以適當的參考指南作為其他細節的補充

    + +
    +

    When called, the Canvas 2D API method CanvasRenderingContext2D.strokeText() strokes the characters in the specified string beginning at the coordinates specified, using the current pen color. In the terminology of computer graphics, "stroking" text means to draw the outlines of the glyphs in the string without filling in the contents of each character with color.

    + +

    The text is drawn using the context's current font as specified in the context's {{domxref("CanvasRenderingContext2D.font", "font")}} property.

    + +

    The placement of the text relative to the specified coordinates are determined by the context's textAlign, textBaseline, and direction properties. textAlign controls the placement of the string relative to the X coordinate specified; if the value is "center", then the string is drawn starting at x - (stringWidth / 2), placing the specified X-coordinate in the middle of the string. If the value is "left", the string is drawn starting at the specified value of x. And if textAlign is "right", the text is drawn such that it ends at the specified X-coordinate.

    + +

    (etc etc etc...)

    + +

    You can, optionally, provide a fourth parameter that lets you specify a maximum width for the string, in pixels. If you provide this parameter, the text is compressed horizontally or scaled (or otherwise adjusted) to fit inside a space that wide when being drawn.

    + +

    You can call the fillText() method to draw a string's characters as filled with color instead of only drawing the outlines of the characters.

    +
    + +
    範例：恰到好處！
    + +

    下列是一個針對 strokeText() 方法更好的概述。

    + +
    +

    The {{domxref("CanvasRenderingContext2D")}} method strokeText(), part of the Canvas 2D API, strokes—that is, draws the outlines of—the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. The text is drawn using the context's current {{domxref("CanvasRenderingContext2D.font", "font")}}, and is justified and aligned according to the {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, and {{domxref("CanvasRenderingContext2D.direction", "direction")}} properties.

    + +

    For more details and further examples, see {{SectionOnPage("/zh-TW/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Text")}} in the Learning Area as well as our main article on the subject, Drawing text.

    +
    + +

    涵蓋所有相關的範例

    + +

    使用範例來進一步闡明每一個使用到的參數以及任何可能出現的少數邊際案例是非常重要的。使用範例來展示常見問題以及可能引發問題的情況及他們的解決方式。

    + +

    一般而言會期待多數的頁面都可以包含一到多個範例，最好有超過一個範例。

    + +

    每一個範例須有前導的文字用於說明該範例所為何事以及讀者在閱讀及試驗該範例前的須知事項。

    + +
    程式碼範例
    + +

    每一段程式碼都應具有其如何運作的說明。大型段落的程式碼應切割成更小的部分以便於進行個別的描述。

    + +

    每一段程式碼之後的文字應解釋所有相關資訊並控制好描述細節的程度：

    + + + +

    當加入實際範例時，所有位於範例區域內的 {{HTMLElement("pre")}} 區塊會在執行範例前串聯起來，這便於讓你把 HTML 、 CSS 、 JavaScript 分開來處理，並讓它們擁有自己的描述、標題等。這使得程式碼的建檔變得更強大且更彈性。

    + +

    過於簡短的文章很難被找到

    + +

    如果文章的篇幅過於簡短，那可能搜尋引擎無法對其合理的索引（甚至根本無法索引）。根據經驗，文章的本體應最少有 250-300 字的篇幅。不用特別對文章內容充數，把這個原則當作最低的目標要求就足夠了。

    -

    章節、段落與換行

    +

    標題

    -

    請按照遞增順序使用標題級別：首先是 {{HTMLElement("h2")}}，其次是{{HTMLElement("h3")}}，接著是 {{HTMLElement("h4")}}，不要跳過級別。H2 是允許的最高級別，因為 H1 要留給頁面標題。若你需要超過四、五個級別的標題，請考慮將該文章拆分為幾篇更小的文章並創建登陸頁面，然後用巨集 {{TemplateLink("Next")}}、{{TemplateLink("Previous")}} 和 {{TemplateLink("PreviousNext")}} 將他們連結起來。

    +

    當開啟新的章節段落務必要加上標題。標題的層級以遞減的方式排序： {{HTMLElement("h2")}} 再來是 {{HTMLElement("h3")}} 再來是 {{HTMLElement("h4")}} ，不要跳過任何一個層級。

    -

    在你鍵盤上的 Enter (或 return) 鍵會開一個新的段落。如果希望插入新的一行中間沒有空白，就同時按下 Shift 和 Enter 鍵。

    +

    因為 H1 已經被保留作為頁面的標題使用，因此 H2 是章節段落可使用的最高層級標題。如果使用到超過三或四個等級的標題，請考慮把文章重新劃分成數個篇幅更短的文章並提供一個目錄頁面。

    -

    Don't create single subsections -- you don't subdivide a topic into one. It's either two subheadings or more or none at all. 

    +

    標題的為與不為

    -

    Don't have bumping heads, which are headings followed immediately by headings. Aside from looking horrible, it's helpful to readers if every heading has at least a brief intro after it to introduce the subsections beneath.

    +