スタイルガイド

このスタイルガイドは、コアドキュメントチームに属さないすべての人を対象としています。このドキュメントを、適切な言葉の選択について決定するための入門書として使用してください。

ここで説明されているガイドラインに加えて、迷う場合は、Googleスタイルガイドを参考にしてください。

表現とトーン

• 能動態を使用してください。ユーザーを指導する教師になったつもりで考えてください。
• 現在形で記述してください。学習者は、私たちが求めているように、実装例やフォルダーを確認している可能性があります。
• 未来形は、結果を示す場合にのみ控えめに使用してください。
  • 使用例：リクエストを送信すると、レスポンスには次の情報が含まれます。
  • 避けるべき例：新しいウィンドウが表示されます。
• 簡潔で分かりやすい短い文章を書きましょう。書いた文章全体を言う際に息継ぎが必要な場合は、2つの文章に分割してください。

タイトル

• 手順のトピックには動名詞を使用しないでください。

  • 使用例：自動化エンジンの選択
  • 避けるべき例：自動化エンジンの選択

• タイトルにはセンテンスケースを使用してください

  • 使用例：自動化エンジンの選択
  • 避けるべき例：自動化エンジンの選択

• -ing動詞で始まらない名詞句を使用してください。

  • 使用例：Nightwatch APIの概要
  • 避けるべき例：Nightwatch APIについて

テキストの書式設定

• 太字の使い過ぎは避けましょう。UI要素をアクションとして参照する場合にのみ太字を適用してください。
  • 使用例：自動化ダッシュボードのアクセスキーをクリックします。
  • 避けるべき例：BrowserStackアクセスキーは、自動化ダッシュボードから取得できます。
• イタリック体を使用しないでください。
• 下線を使用しないでください。
• すべての文章にセンテンスケースを使用してください。製品名、業界用語、BrowserStack固有の機能/キーワードを除き、単語を大文字にしないでください。
  • 使用例：Python、ローカルテスト、Chrome
  • 避けるべき例：セッションID、ログ、デスクトップ、認証
• 専門用語は控えめに使用してください。可能な限り、簡単な言葉を使うように心がけてください。
  • オプション情報を示すために括弧（）を使用しないでください。例えば、
  • 避けるべき例：ハブは複数のマシン（ノード）でテストを同時に実行します。
  • 使用例：ハブは複数のマシンまたはノードでテストを同時に実行します。
• ファイル名、ファイルパス、インラインコードを示すには、コードフォントを使用してください。
• 入力値にはコードフォーマットを使用してください。例：abcボックスに、abcと入力します。

フォルダー/Webナビゲーション

• フォルダーナビゲーション
  • 使用例：/opt/homeディレクトリに移動します。
  • 使用例：/opt/homeディレクトリに移動し、abc.jsファイルを開きます。
  • 避けるべき例：/opt/homeディレクトリに移動します。
• Webナビゲーション
  • 使用例：https://localhost:45691にアクセスし、BrowserStackの認証情報を使用してログインします。
  • 避けるべき例：https://localhost:45691を参照し、BrowserStackの認証情報を使用してログインします。

リスト

• すべてのリストには、リストの機能を説明する導入文が必要です。
• 特定の順序で実行する必要がある手順には、番号付きリストを使用してください。
• 並列的な文章構造を維持してください。例については、以下を参照してください。
  • BrowserStackの認証情報を設定する
  • ジョブの結果にBrowserStackのテスト結果を埋め込む
• 項目が1つだけの場合は、箇条書き（番号または記号）を使用しないでください。リストを作成するには、少なくとも2つの項目が必要です。このような場合は、文章に変換してください。