Richtlinien zum Formatieren von Text

  • Artikel

Die konsistente und angemessene Verwendung von Fett-, Kursiv- und Codeformatierungen von Textelementen verbessert die Lesbarkeit und hilft bei der Vermeidung von Missverständnissen.

Fett

Schreiben Sie UI-Elemente wie Menüs, Dialogfeldnamen und Eingabefeldnamen fett.

Beispiele

  • Richtig: Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie Hinzufügen > Neues Element aus.
  • Falsch: Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie dann „Hinzufügen“ > „Neues Element“ aus.
  • Falsch: Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie dann Hinzufügen > Neues Element aus.

Kursiv

Verwenden Sie Kursivschrift für Folgendes:

  • Einführung neuer Begriffe zusammen mit einer Definition oder Erläuterung.
  • Dateinamen, Ordnernamen, Pfade.
  • Benutzereingabe.

Beispiele

  • Richtig: In App Service wird eine App in einem App Service-Plan ausgeführt. Mit einem App Service-Plan werden mehrere Computeressourcen definiert, auf denen eine Web-App ausgeführt wird.
  • Falsch: In App Service wird eine App in einem „App Service-Plan“ ausgeführt. Mit einem App Service-Plan werden Computeressourcen definiert, auf denen eine Web-App ausgeführt werden kann.
  • Richtig: Ersetzen Sie den Code in HttpTriggerCSharp.cs durch den folgenden Code.
  • Falsch: Ersetzen Sie den Code in HttpTriggerCSharp.cs durch den folgenden Code.
  • Richtig: Geben Sie ContosoUniversity als Name ein, und wählen Sie Hinzufügen aus.
  • Falsch: Geben Sie „ContosoUniversity“ als Name ein, und wählen Sie Hinzufügen aus.

Codeformat

Verwenden Sie das Codeformat für Folgendes:

  • Codeelemente, z.B. Methodennamen, Eigenschaftennamen und Schlüsselwörter.
  • SQL-Befehle
  • NuGet-Paketnamen
  • Befehlszeilenbefehle*
  • Datenbanktabellennamen und Datenbankspaltennamen
  • Ressourcennamen, die nicht lokalisiert werden sollten (z. B. die Namen virtueller Computer)
  • URLs, die nicht klickbar sein sollen

Warum? In älteren Styleguides wird für viele dieser Textelemente das Fettformat angegeben. Weil aber die meisten Artikel lokalisiert werden, zeigt das Codeformat dem Übersetzer/der Übersetzerin, dass dieser Teil des Texts nicht übersetzt wird.

Das Codeformat kann inline sein (eingeschlossen in `) oder aus umgrenzten Codeblöcken bestehen (eingeschlossen in ```), die sich über mehrere Zeilen erstrecken. Fügen Sie längere Codeausschnitte und -pfade in umgrenzte Codeblöcke ein.

* Verwenden Sie in Befehlszeilenbefehlen Schrägstriche in Dateipfaden, wenn sie auf allen Plattformen unterstützt werden. Verwenden Sie umgekehrte Schrägstriche, um Befehle zu veranschaulichen, die auf Windows ausgeführt werden, wenn nur umgekehrte Schrägstriche unterstützt werden. Beispielsweise funktionieren Schrägstriche in der .NET-CLI auf allen Plattformen, sodass Sie dotnet build foldername/filename.csproj anstelle von dotnet build foldername\filename.csproj verwenden würden.

Beispiele für die Verwendung von Inlineformaten

  • Richtig: Standardmäßig interpretiert das Entity Framework eine Eigenschaft mit dem Namen Id oder ClassnameID als Primärschlüssel.
  • Falsch: Standardmäßig interpretiert das Entity Framework eine Eigenschaft mit dem Namen Id oder ClassnameI als Primärschlüssel.
  • Richtig: Das Paket Microsoft.EntityFrameworkCore bietet Laufzeitunterstützung für EF Core.
  • Falsch: Das Paket Microsoft.EntityFrameworkCore bietet Laufzeitunterstützung für EF Core.

Beispiele für umgrenzte Codeblöcke

  • Richtig: Es werden keine Befehle von Anweisungen, die nur IQueryable ändern, an die Datenbank gesendet, wie z. B. im folgenden Code:

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

  • Falsch: Es werden keine Befehle von Anweisungen, die nur IQueryable ändern, an die Datenbank gesendet, z. B. var students = context.Students.Where(s => s.LastName == "Davolio").

  • Richtig: Wenn Sie beispielsweise das Skript Get-ServiceLog.ps1 im Verzeichnis C:\Scripts ausführen möchten, geben Sie Folgendes ein:

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

  • Falsch: Wenn Sie beispielsweise das Skript Get-ServiceLog.ps1 im Verzeichnis C:\Scripts ausführen möchten, geben Sie Folgendes ein: „C:\Scripts\Get-ServiceLog.ps1“.

  • Alle umgrenzten Codeblöcke müssen ein genehmigtes Sprachtag haben. Eine Liste von unterstützten Sprachtags finden Sie unter Einbinden von Code in Dokumenten.

Platzhalter

Wenn der Benutzer einen Teil einer Eingabezeichenfolge durch eigene Werte ersetzen soll, verwenden Sie Platzhaltertext, der durch eckige Klammern markiert ist (Kleiner-als- < und Größer-als-Zeichen >).

Option 1: Verwenden Sie Codeformatierungen, um das Platzhalterwort oder den umgebenden Ausdruck einzuschließen. Sie können z. B. einzelne Graviszeichen ` für die Inlinecodeformatierung für einen einzelnen Ausdruck oder drei Graviszeichen ``` für die Formatierung mit Codefencing verwenden.

`az group delete -n <ResourceGroupName>`

Gerendert:

az group delete -n <ResourceGroupName>

oder

Option 2: Verwenden Sie einen umgekehrten Schrägstrich \ als Escapezeichen für die spitzen Klammern in Markdown, z. B. \< und \>. Während nur das erste Escapezeichen in der linken spitzen Klammer \< erforderlich ist, ist es aus Gründen der Konsistenz auch möglich, für die schließende Klammer \> ein Escapezeichen zu verwenden. Im gerenderten HTML-Code sieht der Leser das Escapezeichen nicht:

az group delete -n \<ResourceGroupName\>

Gerendert:

az group delete -n <ResourceGroupName>

Informieren Sie den Leser über den Platzhalter: Erläutern Sie dem Leser im Text vor solchen Platzhalterbeispielen, dass der Text in Klammern entfernt und durch echte Werte ersetzt werden muss. Es wird empfohlen, Benutzereingaben kursiv zu formatieren. Sie können die Kursivformatierung innerhalb von Inlinecode in spitzen Klammern verwenden:

Ersetzen Sie im folgenden Beispiel den Platzhaltertext <ResourceGroupName> durch ihren eigenen Ressourcengruppennamen.

Achtung

Die Microsoft Learn-Website rendert <keinen Platzhaltertext> , der spitzen Klammern verwendet, in Fällen, in denen die Klammern nicht ordnungsgemäß mit Escape versehen sind oder der Text nicht codeformatiert ist. Der Microsoft Learn-Buildprozess interpretiert den <Platzhalterbegriff> als HTML-Tag, das für den Browser des Lesers gefährlich sein könnte, und kennzeichnet ihn als nicht zulässiges html-Tag. Im Buildbericht wird ein Vorschlag angezeigt, und das Platzhalterwort wird in der Ausgabe der Microsoft Learn-Seite nicht gerendert.

Damit bei Platzhaltern keine Inhalte verloren gehen, verwenden Sie die code-Formatierung oder Escapezeichen (\<\>), wie weiter oben beschrieben.

Es wird davon abgeraten, geschweifte Klammern { } als syntaktische Platzhalter zu verwenden. Leser können Platzhalter in geschweiften Klammern mit der Notation verwechseln, die in folgenden Fällen verwendet wird:

  • Ersetzbarer Text
  • Formatzeichenfolgen
  • Zeichenfolgeninterpolierung
  • Textvorlagen
  • Ähnliche Programmierkonstrukte

Groß-/Kleinschreibung und Abstandszeichen: Sie können Platzhalternamen durch Bindestriche („Kebabschreibweise“) oder Unterstriche trennen, oder Sie verwenden die Pascal-Schreibweise. Bei der Kebabschreibweise treten möglicherweise Syntaxfehler auf, und sie kann zu Konflikten mit Unterstreichungen führen. Eine Schreibweise nur in Großbuchstaben kann in vielen Sprachen zu Konflikten mit benannten Konstanten führen, sie können aber auch dazu verwendet werden, den Platzhalternamen hervorzuheben.

<Resource-Group-Name> oder <ResourceGroupName>

Überschriften und Linktext

Verwenden Sie kein Inlineformat wie Kursiv oder Fett für Überschriften oder Linktext.

Warum?

Benutzer verlassen sich auf das Standardformat für Linktext, um Textelemente als klickbare Links zu identifizieren. Einen Link als kursiv zu formatieren, kann beispielsweise dazu führen, dass der Text nicht als Link erkannt werden kann. Überschriften haben ihre eigenen Formate. Kombinieren Sie nicht mehrere Formate miteinander.

Beispiele für Überschriften und Linktext

  • Richtig: Die Datei function.json wird vom NuGet-Paket Microsoft.NET.Sdk.Functions generiert.

  • Falsch: Die Datei function.json wird vom NuGet-Paket Microsoft.NET.Sdk.Functions generiert.

  • Richtig:

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

  • Falsch:

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

Tasten und Tastenkombinationen

Beachten Sie die folgenden Konventionen, wenn Sie auf Tasten oder Tastenkombinationen verweisen:

  • Schreiben Sie Tastennamen groß.
  • Schließen Sie Tastennamen in die HTML-Tags <kbd> und </kbd> ein.
  • Verwenden Sie das Pluszeichen (+), um Tasten zu kombinieren, die gleichzeitig gedrückt werden müssen.

Beispiele für Tasten und Tastenkombinationen

  • Richtig: Drücken Sie ALT+STRG+S.
  • Falsch: Drücken Sie ALT+STRG+S.
  • Falsch: Drücken Sie ALT+CTRL+S.

Ausnahmen

Die Richtlinien des Styleguides sind keine strengen Regeln. Gehen Sie aber in einem Kontext, in dem diese Richtlinien die Lesbarbarkeit beeinträchtigen, anders vor. Zum Beispiel kann eine HTML-Tabelle, die überwiegend Codeelemente enthält, unübersichtlich sein, wenn überall das Codeformat verwendet wird. In diesem Kontext würde sich das Fettformat empfehlen.

Wenn Sie in Fällen, in denen normalerweise Code erforderlich ist, ein anderes Textformat verwenden, stellen Sie sicher, dass der Text in lokalisierten Versionen des Artikels übersetzt werden kann. Das Codeformat ist das einzige Format, das Übersetzungen automatisch verhindert. Bei Szenarien, in denen Sie die Lokalisierung ohne Codeformat verhindern möchten, finden Sie entsprechende Informationen unter Nicht lokalisierte Zeichenfolgen.