次の方法で共有

テキストの書式設定に関するガイドライン

テキスト要素の太字、斜体、およびコード スタイルは、一貫性を保って適切に使用することで、読みやすさを向上させ、誤解を避けることに役立ちます。 テキスト書式設定要素がこのガイダンスでカバーされていない場合は、 Microsoft ライティング スタイル ガイドを参照してください。 次の記事では、テキストの書式設定に関する詳細なガイダンスを提供します。

UI 要素

メニュー項目、ダイアログ名、テキスト ボックスの名前などの UI 要素は、太字のテキストにする必要があります。

  • 次の操作: ソリューション エクスプローラーで、プロジェクト ノードを右クリックし、[ 追加>新しい項目] を選択します。

  • 誤: ソリューション エクスプローラーで、プロジェクト ノードを右クリックして、[追加] > [新しいアイテム] の順に選択します。

Git リポジトリとブランチ名

Git リポジトリまたはブランチ名を手順で選択または入力するときに、太字のテキストを使用してください。

  • [ブランチ] メニューから [ メイン] を選択します。

  • そうでない場合: ブランチ メニューから [メイン] を選択します。

新しい用語の導入

斜体テキストを使用して、定義または説明と共に新しい用語を導入します。 新しい用語を初めて使用するときは斜体にし、定義または説明には通常のテキストを使用します。

  • 正: App Service では、アプリは "App Service プラン" で実行されます。 App Service プランでは、Web アプリで実行するための一連のコンピューティング リソースを定義します。

  • 誤: App Service では、アプリは "App Service プラン" で実行されます。App Service プランでは、Web アプリで実行するための一連のコンピューティング リソースを定義します。

コード スタイル

次の場合は、コード スタイルを使用します。

  • メソッド名、プロパティ名、言語キーワードなどのコード要素。
  • SQL コマンド
  • NuGet パッケージ名
  • コマンド ライン コマンド*
  • データベース テーブル名と列名
  • ローカライズすべきではないリソース名 (仮想マシン名など)
  • クリック可能にしない URL

なぜですか? 一部のスタイル ガイドでは、これらのテキスト要素の多くに太字が指定されています。 しかし、ほとんどの記事はローカライズされるため、コード スタイルを使用して、テキストのその部分を翻訳せずにそのままにしておくように翻訳者に指示します。

コード スタイルには、"インライン" コード ブロック (` で囲む) か、複数の行にまたがる "フェンスされた" コード ブロック (``` で囲む) を使用できます。 長いコード スニペットとパスは、フェンスされたコード ブロック内に配置します。

* コマンド ライン コマンドでは、すべてのプラットフォームでサポートされている場合は、ファイル パスにスラッシュを使用します。 バックスラッシュのみがサポートされている場合は、Windows で実行されるコマンドを示すためにバックスラッシュを使用します。 たとえば、すべてのプラットフォームの .NET CLI ではスラッシュが機能するため、dotnet build foldername/filename.csproj ではなく dotnet build foldername\filename.csproj を使用します。

インライン スタイルの使用例

  • 正: 既定では、Entity Framework は、Id または ClassnameID という名前のプロパティを主キーとして解釈します。
  • 誤: 既定では、Entity Framework は、Id または ClassnameID という名前のプロパティを主キーとして解釈します。
  • 正: Microsoft.EntityFrameworkCore パッケージは EF Core のランタイム サポートを提供します。
  • 誤: Microsoft.EntityFrameworkCore パッケージは EF Core のランタイム サポートを提供します。

フェンスされたコード ブロックの例

  • 正: 次のコードのように、IQueryable を変更しただけのステートメントでは、データベースにコマンドは送信されません。

        ```csharp
    var students = context.Students.Where(s => s.LastName == "Davolio")
    ```

  • 誤: のように、> を変更しただけのステートメントでは、データベースにコマンドは送信されません。

  • 正: たとえば、Get-ServiceLog.ps1 ディレクトリで C:\Scripts スクリプトを実行するには、次を入力します。

        ```powershell
    C:\Scripts\Get-ServiceLog.ps1
    ```

  • 誤: たとえば、C:\Scripts ディレクトリで Get-ServiceLog.ps1 スクリプトを実行するには、「C:\Scripts\Get-ServiceLog.ps1」を入力します。

  • すべてのフェンスされたコード ブロックには、承認された言語タグが必要です。 サポートされる言語タグの一覧については、docs にコードを含める方法に関するページをご覧ください。

プレースホルダー

段落テキストまたは手続き手順では、ユーザーが自分の情報に置き換えるプレースホルダー テキストに斜体を使用します。

  • This: Enter password (パスワードを入力してください)

  • これを入力しない: "password"は避けてください

  • これ: -pパスワードを入力してください

  • そうでない場合: -p パスワードを 入力してください

入力文字列の一部をユーザーが独自の値で置換する必要がある場合は、山かっこ ("小なり" < および "大なり" > の文字) で囲まれたプレースホルダー テキストを使用します。

オプション 1: コード スタイルを使用して、プレースホルダーの単語または外側の語句を囲みます。 たとえば、単一フレーズのインライン コード書式設定にはシングル バッククォート ` を、コード フェンスされた書式設定にはトリプルクォート ``` を使用できます。

`az group delete -n <ResourceGroupName>`

次のようにレンダリングされます。

az group delete -n <ResourceGroupName>

または

オプション 2: バックスラッシュ文字 \ を \< や \> のように使用して、山かっこ文字をエスケープします。 必要なのは左山かっこに対する最初のエスケープ \< のみですが、閉じかっこに対するエスケープ \> も一貫性を保つ働きをします。 レンダリングされた HTML では、閲覧者にエスケープ文字は表示されません。

az group delete -n \<ResourceGroupName\>

次のようにレンダリングされます。

az group delete -n < ResourceGroupName>

プレースホルダーについて読者に通知する: プレースホルダーの例の前にあるテキストで、角かっこ内のテキストを削除し、実際の値に置き換える必要があることをリーダーに説明します。 ユーザーによる入力には斜体を使用することをお勧めします。 山かっこで囲まれたインライン コード内で斜体を書式設定できます。

次の例で、プレースホルダー テキスト <ResourceGroupName> を独自のリソース グループ名に置き換えてください。

注意事項

Microsoft Learn サイトでは、かっこが正しくエスケープされていない場合や、テキストがコード フォーマットされていない場合、山かっこを使用する <プレースホルダー> テキストはレンダリングされません。 Microsoft Learn のビルド プロセスは、<プレースホルダー> フレーズを閲覧者のブラウザーにとって危険な可能性のある HTML タグとして解釈し、disallowed-html-tag としてフラグを付けます。 ビルド レポートに提案が表示されます。その場合、Microsoft Learn ページ出力にプレースホルダーの単語はレンダリングされません。

プレースホルダーでコンテンツが失われないようにするため、上の説明に従って、code 書式設定かエスケープ文字 (\<\>) を使用してください。

構文のプレースホルダーとして中かっこ { } を使用しないことをお勧めします。 閲覧者は、中かっこのプレースホルダーと、次に使用される同じ表記を混同する可能性があります。

  • 置換可能なテキスト
  • 書式指定文字列
  • 文字列補間
  • テキスト テンプレート
  • 類似のプログラミング コンストラクト

大文字と小文字の区別およびスペース: プレースホルダー名は、ハイフンで区切る ("ケバブ ケース") ことやアンダースコアで区切ることができます。また、パスカル ケースを使用してそうすることもできます。 ケバブ ケースを使用すると構文エラーが発生する場合があり、アンダースコアは下線と競合する可能性があります。 すべての大文字を使用すると、多くの言語で名前付き定数と競合する可能性がありますが、プレースホルダー名にも注意が必要になる場合があります。

<Resource-Group-Name> または <ResourceGroupName>

見出し

斜体、太字、インライン コード スタイルなどのインライン スタイルを見出しに適用しないでください。

なぜですか? 見出しには独自のスタイルがあり、他のスタイルを混在させると不整合が発生します。

  • This: Microsoft.NET.Sdk.Functions パッケージをインポートする

  • これ以外: Microsoft.NET.Sdk.Functions パッケージをインポートする

リンク テキスト

斜体や太字などのインライン スタイルを適用してテキストをリンクしないでください。

なぜですか? ユーザーは、標準のハイパーリンク テキストを頼りに、テキスト要素をクリック可能なリンクとして識別します。 たとえば、リンクを斜体としてスタイル設定すると、テキストがリンクであるという事実を隠すことができます。

これ以外: NuGet パッケージ Microsoft.NET.Sdk.Functions は、function.json ファイルを生成します。

キーおよびキーボード ショートカット

キーまたはキーの組み合わせを参照する場合、次の規約に従います。

  • キー名の最初の文字を大文字にする。
  • キー名を <kbd> と </kbd> の HTML タグで囲む。
  • ユーザーが同時に選択するキーをつなげるには、"+" を使う。

キーとキーボード ショートカットの例

  • 正: Alt+Ctrl+S キーを選択します。
  • 誤: ALT + CTRL + S キーを同時に押します。
  • 誤: ALT+CTRL+S キーを同時に押します。

例外

一貫したスタイル ガイドラインにより、信頼性の高いカスタマー エクスペリエンスが作成され、作成プロセスが簡略化されます。 これらのガイドラインの例外は慎重に検討する必要があります。

例外で、通常はコードを呼び出す代替テキスト スタイルを使用する必要がある場合は、ローカライズされたバージョンの記事でテキストを翻訳しても問題がないことを確認してください。 コード スタイルを使用しないでローカライズを防止する必要があるシナリオについては、「ローカライズしない文字列」を参照してください。