Share via

Richtlijnen voor het opmaken van tekst

  • Artikel

Als de stijlen Vet, Cursief en Code consistent en correct worden gebruikt voor tekstelementen, verbetert dit de leesbaarheid en ontstaan er geen interpretatiefouten.

Vet

Gebruik vet voor elementen in de gebruikersinterface, zoals menuopties, namen van dialoogvensters en namen van invoervelden.

Voorbeelden

  • Dit: Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt en selecteer vervolgens Nieuw item toevoegen>.
  • Niet dit: Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt en selecteer vervolgens Nieuw item toevoegen > .
  • Niet dit: Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt en selecteer vervolgens Nieuw item toevoegen>.

Cursief

Gebruik cursief voor:

  • Nieuwe termen die u introduceert in combinatie met een definitie of uitleg.
  • Bestandsnamen, mapnamen, paden.
  • Gebruikersinvoer.

Voorbeelden

  • Dit: In App Service worden apps uitgevoerd op basis van een App Service-plan. Een App Service-plan omvat een reeks rekenresources waarop web-apps kunnen worden uitgevoerd.
  • Niet dit: In App Service wordt een app uitgevoerd in een 'App Service plan'. Een App Service-plan definieert een set rekenresources waarop een web-app kan worden uitgevoerd.
  • Dit: Vervang de code in HttpTriggerCSharp.cs door de volgende code.
  • Niet dit: Vervang de code in HttpTriggerCSharp.cs door de volgende code.
  • Dit: Voer ContosoUniversity in voor de Naamen selecteer vervolgens Toevoegen.
  • Niet dit: Voer 'ContosoUniversity' in voor de Naam en selecteer vervolgens Toevoegen.

De stijl Code

Gebruik codestijl voor:

  • Code-elementen, zoals methodenamen, eigenschapsnamen en taaltrefwoorden.
  • SQL-opdrachten
  • NuGet-pakketnamen
  • Opdrachtregelopdrachten*
  • Databasetabel- en kolomnamen
  • Resourcenamen die niet moeten worden gelokaliseerd (zoals namen van virtuele machines)
  • URL's waarop niet kan worden geklikt

Hoe komt dat? In oudere stijlgidsen staat dat vet moet worden gebruikt voor veel van deze tekstelementen. De meeste artikelen worden echter gelokaliseerd en door de codestijl weet de vertaler dat dat deel van de tekst niet moet worden vertaald.

Codestijl kan inline zijn (omgeven door ') of omheinde codeblokken (omgeven door ''') die meerdere regels omvatten. Langere codefragmenten en paden moeten in speciale codeblokken worden geplaatst.

* Gebruik in opdrachtregelopdrachten slashes in bestandspaden als deze op alle platforms worden ondersteund. Gebruik backslashes om opdrachten te illustreren die worden uitgevoerd in Windows, wanneer alleen backslashes worden ondersteund. Zo werken slashes bijvoorbeeld op de .NET CLI op alle platforms, dus u gebruikt dotnet build foldername/filename.csproj in plaats dotnet build foldername\filename.csprojvan .

Voorbeelden met inlinestijlen

  • Dit: In Entity Framework worden eigenschappen met de naam Id of ClassnameID automatisch als primaire sleutel gezien.
  • Niet dit: In Entity Framework worden eigenschappen met de naam Id of ClassnameID automatisch als primaire sleutel gezien.
  • Dit: Het pakket Microsoft.EntityFrameworkCore biedt runtimeondersteuning voor EF Core.
  • Niet dit: Het pakket Microsoft.EntityFrameworkCore biedt runtimeondersteuning voor EF Core.

Voorbeelden van speciale codeblokken

  • Dit: Er worden geen opdrachten verzonden naar de database als er instructies worden gegeven waarmee alleen een IQueryable wordt gewijzigd, zoals bij de volgende code:

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

  • Niet dit: er worden geen opdrachten naar de database verzonden door instructies die alleen een IQueryable wijzigen, zoals var students = context. Students.Where(s => s.LastName == "Davolio").

  • Dit: Voer het volgende in om het script Get-ServiceLog.ps1 uit te voeren in de map C:\Scripts:

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

  • Niet dit: Voer het volgende in om het script Get-ServiceLog.ps1 uit te voeren in de map C:\Scripts: "C:\Scripts\Get-ServiceLog.ps1."

  • Alle afgebakende codeblokken moeten een goedgekeurde taalcode hebben. Zie Code opnemen in documenten voor een lijst met ondersteunde taalcodes.

Tijdelijke aanduidingen

Als u wilt dat de gebruiker een deel van een invoertekenreeks vervangt door eigen waarden, gebruikt u tijdelijke aanduidingen voor tekst die is gemarkeerd met punthaken (kleiner dan < en groter dan > tekens).

Optie 1: Gebruik codestijl om het woord van de tijdelijke aanduiding of de omringende woordgroep te plaatsen. U kunt bijvoorbeeld enkele backticks ' gebruiken voor inline-codeopmaak voor één woordgroep, of driemaal tikken ''' voor omgeleide opmaak met code.

`az group delete -n <ResourceGroupName>`

Weergegeven als:

az group delete -n <ResourceGroupName>

of

Optie 2: Gebruik een backslash \ om de punthaaktekens in Markdown te laten ontsnappen, zoals \< en \>. Hoewel alleen de eerste escape op de linkerhoekhaak \< is vereist, werkt het sluiten van de haak \> ook voor consistentie. In de weergegeven HTML wordt het escape-teken niet weergegeven voor de lezer:

az group delete -n \<ResourceGroupName\>

Weergegeven als:

az group delete -n <ResourceGroupName>

Informeer de lezer over de tijdelijke aanduiding: leg de lezer in de tekst voorafgaand aan dergelijke voorbeelden van tijdelijke aanduidingen uit dat de tekst tussen vierkante haken moet worden verwijderd en moet worden vervangen door echte waarden. U wordt aangeraden cursief te gebruiken voor gebruikersinvoer. U kunt cursief opmaken met inlinecode tussen haakjes:

Vervang in het volgende voorbeeld de tekst <ResourceGroupName> van de tijdelijke aanduiding door de naam van uw eigen resourcegroep.

Waarschuwing

De Microsoft Learn-site geeft <geen tijdelijke aanduiding> weer waarin punthaken worden gebruikt in gevallen waarin de haken niet goed zijn uitgetekend of de tekst niet in code is opgemaakt. Tijdens het buildproces van Microsoft Learn wordt de woordgroep van de <tijdelijke aanduiding> geïnterpreteerd als een HTML-tag die gevaarlijk kan zijn voor de browser van de lezer en wordt deze gemarkeerd als een niet-toegestane html-tag. U ziet een suggestie in het buildrapport en het woord van de tijdelijke aanduiding wordt niet weergegeven in de uitvoer van de Microsoft Learn-pagina wanneer dat gebeurt.

Als u inhoudsverlies in tijdelijke aanduidingen wilt voorkomen, gebruikt u code opmaak of escapetekens (\<\>) zoals eerder beschreven.

We raden het gebruik van accolades { } als syntactische tijdelijke aanduidingen af. Lezers kunnen tijdelijke aanduidingen voor accolades verwarren met dezelfde notatie die wordt gebruikt in:

  • Vervangbare tekst
  • Tekenreeksen opmaken
  • Tekenreeksinterpolatie
  • Tekstsjablonen
  • Vergelijkbare programmeerconstructies

Hoofdletters en afstand: u kunt namen van tijdelijke aanduidingen scheiden met afbreekstreepjes ('ieën geval') of met onderstrepingstekens, of u kunt dit doen met behulp van Pascal-hoofdletters. In het geval van een kebabcase kunnen syntaxisfouten ontstaan en onderstrepingstekens kunnen conflicteren met onderstrepen. Hoofdletters kunnen in veel talen een conflict veroorzaken met benoemde constanten, maar het kan ook de aandacht vestigen op de naam van de tijdelijke aanduiding.

<Resource-Group-Name> of <ResourceGroupName>

Koppen en tekst van koppelingen

Pas geen inlinestijl zoals cursief of vet toe op koppen of hyperlinktekst.

Waarom?

Mensen herkennen tekst met de reguliere koppelingsopmaak als koppelingen waar ze op kunnen klikken. Het cursief maken van een koppeling kan bijvoorbeeld verhullen dat de tekst een koppeling is. Koppen hebben hun eigen stijl en het ziet er rommelig uit om daar ook andere stijlen in te gebruiken.

Voorbeelden van koppen en koppelingstekst

  • Dit: het bestand function.json wordt gegenereerd door het NuGet-pakket Microsoft.NET.Sdk.Functions.

  • Niet dit: het bestand function.json wordt gegenereerd door het NuGet-pakket Microsoft.NET.Sdk.Functions.

  • Dit:

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

  • Niet dit:

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

Toetsen en toetsenbordsneltoetsen

Volg deze conventies om te verwijzen naar toetsen of toetsencombinaties:

  • Schrijf de eerste letter van de toetsnamen in hoofdletters.
  • Plaats de sleutelnamen tussen <kbd> en </kbd> HTML-tags.
  • Gebruik '+' om sleutels samen te voegen die de gebruiker op hetzelfde moment selecteert.

Voorbeelden van toetsen en sneltoetsen

  • Dit: Selecteer Alt+Ctrl+S.
  • Niet dit: Druk op Alt+Ctrl+S.
  • Niet dit: Druk op ALT+CTRL+S.

Uitzonderingen

Er zijn altijd uitzonderingen op de stijlrichtlijnen. Wanneer ze de leesbaarheid schaden, doet u iets anders. Een HTML-tabel met voornamelijk code-elementen ziet er mogelijk te rommelig uit als overal de stijl Code wordt gebruikt. U kunt in deze context vetgedrukte stijlen kiezen.

Als u een alternatieve tekststijl kiest waar normaal gesproken code is vereist, controleert u of de tekst in gelokaliseerde versies van het artikel kan worden vertaald. Code is de enige stijl waarbij vertaling automatisch wordt verhinderd. Zie Niet-gelokaliseerde tekenreeksen als u lokalisatie wilt voorkomen zonder codestijl te gebruiken.