Homebrew 文件

散文風格指南

這是一組 Homebrew 散文文件風格和用法的指南，目標讀者為使用者、貢獻者和維護人員（與可執行電腦程式碼相對）。它適用於 Homebrew/brew 儲存庫中的 docs 中的文件、公告電子郵件，以及與 Homebrew 社群的其他通訊。

這不適用於任何 Ruby 或其他電腦程式碼。你可以使用它來提供從電腦程式碼中擷取的技術文件，例如嵌入式手冊頁，但這只是一個建議。

目標和受眾

Homebrew 散文文件的首要目標是與其使用者和貢獻者的社群溝通。「使用者」在此包含「貢獻者」；無論你看到「使用者」，都可以替換為「使用者和貢獻者」。

易於理解比任何特定的風格指南都重要。

使用者優先於維護人員，除了在特別針對維護人員的文件中。

Homebrew 的受眾包括具有廣泛教育和經驗的使用者，以及以英語為非母語的使用者。我們的目標是盡可能支援這些使用者。

我們力求「正確」但不是「花俏」的用法。想想報紙文章，而不是學術論文。

這是一組使用人類判斷力應用的指南，而不是一組嚴格的規則。它就像 經濟學人風格指南 或 加納現代美式用法。它不像 Ruby 風格指南。這裡的所有指南都開放供詮釋和討論。100% 符合這些指南不是目標。

這份文件的目的是幫助作者做出有關清晰度、風格和一致性的決策。它不是為了幫助解決關於誰更了解英語的爭論。不要使用這份文件來當個混蛋。

指南

我們偏好

風格和用法

• 一般來說，英式/聯邦英語優於美式英語
• 「例如」和「即」：繼續使用「例如」或「即」代替拼寫它們。不用擔心在它們後面加上逗號。
  • 「e.g.」表示「例如」；「i.e.」表示「也就是說」
• 使用逗號隔開不重要的從屬子句

人稱代名詞

• 我們尊重所有人選擇人稱代名詞的方式
• 當某人的性別未知時，使用單數「they」
• 非必要時，避免使用特定性別的語言

結構和標記

• 在 h1 標題中使用標題大小寫；在所有其他標題中使用句子大小寫
• 在清單項目末尾加上句點，其中大部分項目都是完整的句子
• 更一般來說，使用並列的清單項目結構
• 如果您願意，可以將所有清單項目大寫，即使它們不是完整的句子；只要在每個清單中保持一致，最好在整個頁面中保持一致
• 使用從屬清單項目，而不是將多個句子長的段落項目放入句子片段清單中
• 除非需要特定功能，否則優先使用 Markdown 而非其他標記格式
  • GitHub 風味 Markdown。GitHub 的實作是標準，句號。

印刷慣例

• 命令和程式碼中的文字文字以 固定寬度字型 樣式顯示
• 程式碼片段中的佔位符以 <...> 括號標記
  • 例如 git remote add <my-user-name> https://github.com/<my-user-name>/homebrew-core.git
• 像 git 和 brew 這樣的命令名稱以 固定寬度字型 樣式顯示
• 在程式碼片段外提到的環境變數不加「$」
  • 例如「將 BLAH 設為 5」，而不是「將 $BLAH 設為 5」
• 句號後一個空格，不是兩個
• 大寫專有名詞
• 除了專有名詞的正常大寫和簡單的內部大寫之外，我們不使用廣泛的非標準大寫、排版或其他品牌名稱樣式
• 沒有「TM」、「™」、「^SM」、「©」、「®」或其他明確的權利所有權或商標標示；當提到品牌名稱時，我們認為這些都是理所當然的
• 像 homebrew/core 這樣的點選名稱以 固定寬度字型 樣式顯示。儲存庫名稱可以以固定寬度字型顯示，例如「Homebrew/homebrew-core」，也可以以連結顯示，例如「Homebrew/homebrew-core」，或以一般文字顯示，例如「Homebrew/homebrew-core」，具體取決於哪一種在特定用途下看起來最好。
  • 但在單一文件中保持一致
  • 將儲存庫名稱大寫，以符合 GitHub 上的使用者和儲存庫名稱。保持點選名稱小寫。
• 逗號
  • 不使用牛津逗號
  • 偏好使用「寬鬆」逗號風格：「有疑慮時，省略」除非為了清楚起見而需要

術語、詞彙和字詞風格

• 「pull request」，而非「Pull Request」
• 「check out」是動詞；「checkout」是名詞
• 拼寫出某些技術詞彙
  • 「repository」，而非「repo」
  • 縮寫時，在任何文件中第一次使用時說明縮寫
• 不過，某些縮寫（在我們的使用者群中幾乎普遍理解）是可以的。
  • 「Mac」是可以的；「Macintosh」沒有必要
• 所有版本都使用「macOS」，描述特定舊版本時使用「OS X」或「Mac OS X」
• 「RuboCop」，而非「Rubocop」
• pull request 是「在」儲存庫中建立的；該儲存庫「在」某個 URL

如何使用這些指南

參閱這些指南，以便在撰寫 Homebrew 文件和溝通時，針對風格和用法做出決策。

修正文件或多個文件中的風格和用法的 PR 是可以的，而且受到鼓勵。僅針對一或兩個風格變更的 PR 有點過多。

針對涉及文件的 PR 或提交提供風格和用法回饋是可以的，而且受到鼓勵。但請記住，這些只是指南，對於任何變更，作者可能已做出明智的選擇，為了理解性或美觀而打破這些規則。