次の方法で共有

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

  • [アーティクル]

テキスト要素の太字、斜体、およびコード スタイルは、一貫性を保って適切に使用することで、読みやすさを向上させ、誤解を避けることに役立ちます。

太字

メニューの選択肢、ダイアログ ボックス名、入力フィールド名などの UI 要素には太字を使用します。

例

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

斜体

次の場合は、斜体を使用します。

  • 定義または説明で新しい用語を使用する。
  • ファイル名、フォルダー名、パス。
  • ユーザーによる入力。

例

  • 正: App Service では、アプリは "App Service プラン" で実行されます。 App Service プランでは、Web アプリで実行するための一連のコンピューティング リソースを定義します。
  • 誤: App Service では、アプリは "App Service プラン" で実行されます。App Service プランでは、Web アプリで実行するための一連のコンピューティング リソースを定義します。
  • 正: HttpTriggerCSharp.cs のコードを次のコードに置き換えます。
  • 誤: HttpTriggerCSharp.cs のコードを次のコードに置き換えます。
  • 正: [名前] に「ContosoUniversity」と入力し、[追加] を選択します。
  • 誤: [名前] に「ContosoUniversity」と入力し、[追加] を選択します。

コード スタイル

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

  • メソッド名、プロパティ名、言語キーワードなどのコード要素。
  • 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")
    ```

  • 誤: var students = context.Students.Where(s => s.LastName == "Davolio") のように、IQueryable を変更しただけのステートメントでは、データベースにコマンドは送信されません。

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

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

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

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

プレースホルダー

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

オプション 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>

見出しとリンク テキスト

斜体や太字などのインライン スタイルは、見出しやハイパーリンク テキストに適用しないでください。

その理由は、

ユーザーは、標準のハイパーリンク テキストを頼りに、テキスト要素をクリック可能なリンクとして識別します。 たとえば、リンクを斜体としてスタイル設定すると、テキストがリンクであるという事実が分かりにくくなります。 見出しには独自のスタイルがあり、異なるスタイルを混在させると、見た目が悪くなります。

見出しとリンク テキストの例

  • 正: function.json ファイルは、NuGet パッケージ Microsoft.NET.Sdk.Functions によって生成されます。

  • 誤: function.json ファイルは、NuGet パッケージ Microsoft.NET.Sdk.Functions によって生成されます。

  • 正:

    ### The Microsoft.NET.Sdk.Functions package

  • 誤:

    ### The *Microsoft.NET.Sdk.Functions* package

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

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

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

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

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

例外

スタイル ガイドラインは、厳格なルールではありません。 読みやすさが損なわれる場合は、別のスタイルを使用してください。 たとえば、大部分がコード要素の HTML テーブルの場合、すべてにコード スタイルを設定すると、非常に見にくくなる場合があります。 このような場合、太字のスタイルを選択することもできます。

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