風格指南

本風格指南適用於任何非核心文件團隊成員。請使用本文件作為入門，針對適當的用字選擇做出決定。

除了此處提及的準則外，如果您感到困惑，請參閱 Google 風格指南 以做出任何決定。

語氣和語調

  • 使用主動語態。將其視為您是使用者引導的老師。
  • 以現在式表達。學習者可能會在我們要求時瀏覽實作範例和資料夾。
  • 僅在表示結果時謹慎使用未來式。
    • 使用：當您發送請求時，回應將包含以下資訊。
    • 避免：將出現新視窗。
  • 撰寫簡短、精確且簡潔的句子。如果您在說出您寫的整個句子時需要換氣，請將其分成兩個句子。

標題

  • 對於程序主題，避免使用動名詞

    • 使用：選擇自動化引擎
    • 避免：選擇自動化引擎

  • 標題使用句子大小寫

    • 使用：選擇自動化引擎
    • 避免：Select an Automation Engine

  • 使用不以 -ing 動詞開頭的名詞片語。

    • 使用：Nightwatch API 總覽
    • 避免：瞭解 Nightwatch API

文字格式設定

  • 避免過度使用粗體。僅在將 UI 元素作為動作參考時才套用粗體。
    • 使用：在 Automate 儀表板上按一下 存取金鑰。
    • 避免：您可以從 Automate 儀表板 取得您的 BrowserStack 存取金鑰。
  • 請勿使用斜體。
  • 避免使用底線。
  • 所有句子皆使用句子大小寫。除了產品名稱、產業術語或 BrowserStack 特定的功能/關鍵字外，請勿將任何單字大寫。
    • 使用：Python、本地測試、Chrome
    • 避免：Session ID、Logs、Desktop、Authentication
  • 謹慎使用術語。盡可能使用較簡單的單字。
    • 避免使用括號 () 來表示選用資訊。例如，
    • 避免：Hub 在多台機器 (節點) 上同時執行測試。
    • 使用：Hub 在多台機器或節點上同時執行測試。
  • 使用 code 字型表示檔案名稱、檔案路徑、行內程式碼。
  • 使用程式碼格式設定輸入值。例如，在 abc 方塊中，輸入 abc。

資料夾/網頁導覽

  • 資料夾導覽
    • 使用：導覽至 /opt/home 目錄。
    • 使用：導覽至 /opt/home 目錄並開啟 abc.js 檔案。
    • 避免：前往 /opt/home 目錄。
  • 網頁導覽

清單

  • 每個清單都需要一個引導句，說明清單的功能。
  • 對於需要依特定順序執行的程序，使用編號清單。
  • 維持平行句子結構。例如，請參閱下方
    • 設定您的 BrowserStack 憑證
    • 將 BrowserStack 測試結果嵌入您的作業結果中
  • 當只有一個項目時，請勿使用項目符號 (數字或符號)；必須至少有兩個項目才能建立清單。在這種情況下，請將其轉換為句子。