Richtlijnen voor het opmaken van tekst

Als de stijlen Vet, Cursief en Code consistent en correct worden gebruikt voor tekstelementen, verbetert dit de leesbaarheid en ontstaan er geen interpretatiefouten. Als een element voor tekstopmaak niet wordt gedekt door deze richtlijnen, raadpleegt u de Microsoft-handleiding voor schrijfstijl. De volgende artikelen bevatten gedetailleerde richtlijnen voor tekstopmaak:

• Algemene tekstelementen opmaken

• Tekst opmaken in instructies

• Algemene elementen van ontwikkelaars opmaken

UI-elementen

UI-elementen, zoals menu-items, dialoogvensternamen en namen van tekstvakken, moeten vetgedrukt zijn.

• Dit: Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt en selecteerNieuw item>.

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

Git-opslagplaats- en vertakkingsnamen

Gebruik vetgedrukte tekst voor Git-opslagplaats- of vertakkingsnamen wanneer deze zijn geselecteerd of ingevoerd in instructies.

• Dit: Selecteer in het branchmenu main.

• Niet dit: Selecteer 'main' in het vertakkingsmenu.

Introducties van nieuwe termen

Gebruik cursieve tekst om een nieuwe term samen met een definitie of uitleg te introduceren. Cursief de nieuwe term de eerste keer dat u deze gebruikt en gebruik vervolgens reguliere tekst voor de definitie of uitleg.

• 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 waarmee een web-app kan worden uitgevoerd.

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

Waarom? Sommige stijlgidsen specificeren vet 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 ze op alle platforms worden ondersteund. Gebruik backslashes om opdrachten te illustreren die worden uitgevoerd in Windows, wanneer alleen backslashes worden ondersteund. Slashes werken bijvoorbeeld op alle platforms in de .NET CLI, dus u gebruikt dotnet build foldername/filename.csproj in plaats dotnet build foldername\filename.csprojvan .

Voorbeelden met inlinestijlen

• Dit: in het Entity Framework worden eigenschappen met de naam Id of ClassnameID automatisch als primaire sleutel gezien.
• Niet dit: in het 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

Gebruik in alineatekst of procedurele stappen cursief voor tijdelijke tekst die gebruikers vervangen door hun eigen gegevens.

• Dit: Voer het wachtwoord in

• Niet dit: Voer 'wachtwoord' in

• Dit: Voer het wachtwoord -p in

• Niet dit: Voer het wachtwoord -p in

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

Optie 1: Gebruik codestijl om het tijdelijke aanduidingswoord of de omvattende woordgroep te plaatsen. U kunt bijvoorbeeld enkele backticks gebruiken voor inline-codeopmaak voor één woordgroep of drieteken ''' voor met code ommuurde opmaak.

`az group delete -n <ResourceGroupName>`

Weergegeven als:

az group delete -n <ResourceGroupName>

of

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

az group delete -n \<ResourceGroupName\>

Weergegeven als:

az group delete -n <ResourceGroupName>

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

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

Let op

De Microsoft Learn-site geeft <geen tijdelijke aanduiding> voor tekst weer waarin punthaken worden gebruikt in gevallen waarin de vierkante haken niet correct worden ontsnapt of de tekst niet met code is opgemaakt. Het buildproces van Microsoft Learn interpreteert de <tijdelijke aanduiding> als een HTML-tag die gevaarlijk kan zijn voor de browser van de lezer en markeert deze als een niet-toegestane html-tag. U ziet een suggestie in het buildrapport en het tijdelijke aanduiding woord wordt niet weergegeven in de microsoft Learn-pagina-uitvoer wanneer dat gebeurt.

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

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

• Vervangbare tekst
• Opmaak van tekenreeksen
• Tekenreeksinterpolatie
• Tekstsjablonen
• Vergelijkbare programmeerconstructies

Hoofdletters en afstand: U kunt namen van tijdelijke aanduidingen scheiden met afbreekstreepjes ('case') of met onderstrepingstekens of met onderstrepingstekens, of u kunt dit doen met behulp van Pascal-hoofdletters. De syntaxis van De case in De case Van Den Kan syntaxisfouten genereren en onderstrepingstekens kunnen conflicteren met onderstreping. Het gebruik van alle hoofdletters kan conflicteren met benoemde constanten in veel talen, maar het kan ook de aandacht vestigen op de naam van de tijdelijke aanduiding.

<Resource-Group-Name> of <ResourceGroupName>

Koppen

Pas geen inlinestijlen zoals cursief, vet of inlinecodestijl toe op hoofdkoppen.

Waarom? Koppen hebben hun eigen stijlen, en door het combineren van andere stijlen ontstaan er inconsistenties.

• Dit: Het Microsoft.NET.Sdk.Functions-pakket importeren

• Niet dit: het Microsoft.NET.Sdk.Functions-pakket importeren

Tekst van koppeling

Gebruik geen inline-stijl zoals cursief of vet voor koppeltekst.

Waarom? Mensen herkennen tekst met de reguliere koppelingsopmaak als koppelingen waar ze op kunnen klikken. Een koppeling cursief opmaken, kan bijvoorbeeld het feit dat de tekst een koppeling is, verdoezelen.

• Dit: Het NuGet-pakket Microsoft.NET.Sdk.Functions genereert het function.json-bestand.

Niet dit: Het NuGet-pakket Microsoft.NET.Sdk.Functions genereert het function.json-bestand.

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 te koppelen die de gebruiker tegelijkertijd selecteert.

Voorbeelden van toetsen en sneltoetsen

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

Uitzonderingen

Consistente stijlrichtlijnen zorgen voor een betrouwbare klantervaring en vereenvoudigen het ontwerpproces. Uitzonderingen op deze richtlijnen moeten zorgvuldig worden overwogen.

Als de uitzondering betrekking heeft op het gebruik van een alternatieve tekststijl die normaal gesproken code aanroept, moet u ervoor zorgen dat u de tekst in gelokaliseerde versies van het artikel kunt vertalen. Zie Niet-gelokaliseerde tekenreeksen als u lokalisatie wilt voorkomen zonder codestijl te gebruiken.