Fastify 風格指南

歡迎

歡迎來到 Fastify 風格指南。本指南旨在為使用我們的開源框架編寫開發人員文件的使用者提供一種慣用的寫作風格。每個主題都精確且解釋詳盡，可協助您編寫使用者可以輕鬆理解和實作的文件。

本指南適用於誰？

本指南適用於任何喜歡使用 Fastify 構建或想為我們的文件做出貢獻的人。您不需要是編寫技術文件的專家。本指南旨在協助您。

請造訪我們網站上的 貢獻 頁面，或閱讀 GitHub 上的 CONTRIBUTING.md 檔案，以加入我們的開源社群。

開始編寫之前

您需要了解以下內容

• JavaScript
• Node.js
• Git
• GitHub
• Markdown
• HTTP
• NPM

考慮您的受眾

在您開始編寫之前，請先思考您的受眾。在這種情況下，您的受眾應該已經了解 HTTP、JavaScript、NPM 和 Node.js。務必將讀者牢記在心，因為他們是消費您內容的人。您想盡可能提供有用的資訊。請考慮他們需要了解的重要事項，以及他們如何理解這些事項。使用讀者可以輕鬆產生共鳴的字詞和參考資料。向社群徵求意見回饋，這有助於您編寫更好的文件，將重點放在使用者和您想達成的目標上。

直接切入重點

給您的讀者一個明確且精確的行動來執行。從最重要的內容開始。這樣，您可以協助他們更快找到他們需要的內容。大多數情況下，讀者傾向於閱讀頁面上的第一個內容，而許多人不會再向下捲動。

範例

比較不好的寫法：冒號對於註冊參數化路徑非常重要。它可以讓框架知道已建立新的參數。您可以將冒號放在參數名稱之前，以便建立參數化路徑。

比較好的寫法：若要註冊參數化路徑，請在參數名稱前加上冒號。使用冒號可讓框架知道它是參數化路徑，而不是靜態路徑。

避免新增影片或圖片內容

請勿將影片或螢幕擷取畫面新增至文件中。這樣更容易在版本控制下進行維護。隨著新更新的持續開發，影片和圖片最終會過時。相反地，請建立參考連結或 YouTube 影片。您可以使用 markdown 中的 [標題](www.websitename.com) 來新增連結。

範例

To learn more about hooks, see [Fastify hooks](https://fastify.dev.org.tw/docs/latest/Reference/Hooks/).

結果

若要深入了解 Hook，請參閱 Fastify Hook。

避免抄襲

請務必避免抄襲其他人的作品。盡可能保持原創性。您可以從他們所做的工作中學習，如果您使用了他們作品中的特定引言，請註明出處。

用字選擇

在撰寫文件時，您需要使用和避免一些事項，以提高讀者的可讀性，並使文件整潔、直接且清晰。

何時使用第二人稱代詞「您」

撰寫文章或指南時，您的內容應以第二人稱（「您」）直接與讀者溝通。這樣更容易就特定主題直接指示他們該做什麼。若要查看範例，請造訪 外掛指南。

範例

比較不好的寫法：我們可以搭配使用以下外掛。

比較好的寫法：您可以搭配使用以下外掛。

根據 維基百科，您 通常是第二人稱代詞。此外，也用來指稱不確定的人，作為更常見的替代選項，以取代非常正式的不定代詞。

何時避免使用第二人稱代詞「您」

正式寫作的主要規則之一，例如參考文件或 API 文件，就是避免使用第二人稱（「您」）或直接稱呼讀者。

範例

比較不好的寫法：您可以將以下建議做為範例。

比較好的寫法：舉例來說，應參考以下建議。

若要檢視實際範例，請參閱 修飾器 參考文件。

避免使用縮寫

縮寫是文字和口語形式的簡短版本，例如使用「don't」代替「do not」。請避免使用縮寫，以提供更正式的語氣。

避免使用帶有屈尊意味的詞語

帶有屈尊意味的詞語包括

• 僅僅
• 簡單
• 只需
• 基本上
• 顯然

讀者可能會覺得使用 Fastify 的框架和外掛並不容易；請避免使用聽起來簡單、容易、冒犯或不敏感的詞語。並非所有閱讀文件的人都具有相同的理解程度。

以動詞開頭

大多數情況下，請以動詞開頭來描述，這樣讀者就可以輕鬆且精確地跟隨指示。偏好使用現在式，因為它比過去式或未來式更容易閱讀和理解。

範例

比較不好的寫法：您需要先安裝 Node.js，才能夠使用 Fastify。

比較好的寫法：安裝 Node.js 以使用 Fastify。

語氣

語氣是表達您的寫作的好方法。請避免在直接陳述時聽起來太過專橫。請了解何時在直陳語氣、祈使語氣和虛擬語氣之間切換。

直陳 - 在陳述事實或提出問題時使用。

範例：由於沒有可用的測試框架，「Fastify 建議撰寫測試的方法」。

祈使 - 在給予指示、動作、命令或撰寫標題時使用。

範例：在開始開發之前安裝相依性。

虛擬 - 在提出建議、假設或非事實陳述時使用。

範例：建議閱讀我們網站上的文件，以全面了解該框架。

使用主動語態，而非被動語態

使用主動語態是傳達文件的更精簡且直接的方式。

範例

被動：npm 安裝節點相依性和套件。

主動：npm 安裝套件和節點相依性。

寫作風格

文件標題

在 /docs/ 目錄中建立新的指南、API 或參考時，請使用簡短的標題，以最能描述您的文件主題。以烤肉串式命名您的檔案，並避免使用 Raw 或 camelCase。若要深入了解烤肉串式，您可以造訪這篇關於 Case Styles 的 medium 文章。

範例:

hook-and-plugins.md,

adding-test-plugins.md,

removing-requests.md.

超連結

超連結應具有清楚的標題，說明其參考的內容。您的超連結應該如下所示

<!-- More like this -->

// Add clear & brief description
[Fastify Plugins] (https://fastify.dev.org.tw/docs/latest/Plugins/)

<!--Less like this -->

// incomplete description
[Fastify] (https://fastify.dev.org.tw/docs/latest/Plugins/)

// Adding title in link brackets
[](https://fastify.dev.org.tw/docs/latest/Plugins/ "fastify plugin")

// Empty title
[](https://fastify.dev.org.tw/docs/latest/Plugins/)

// Adding links localhost URLs instead of using code strings (``)
[https://127.0.0.1:3000/](https://127.0.0.1:3000/)

請在您的文件中盡可能包含重要的參考資料，但為初學者編寫時，請避免出現過多連結，以免分散注意力。