Delen 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 Nieuw item toevoegen>.
  • Niet dit: Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt en selecteer Nieuw item toevoegen > .
  • Niet dit: Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt en selecteer 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 waarmee een web-app kan worden uitgevoerd.
  • Dit: Vervang de code in HttpTriggerCSharp.cs door de volgende code.
  • Niet dit: Vervang de code door HttpTriggerCSharp.cs de volgende code.
  • Dit: Voer ContosoUniversity in voor de naam en 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

Waarom? 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 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

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>

or

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: In de tekst die voorafgaat aan dergelijke voorbeelden van tijdelijke aanduidingen, wordt aan de lezer uitgelegd 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. Hoofdletters kunnen 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 en tekst van koppelingen

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

Waarom?

Mensen herkennen tekst met de reguliere koppelingsopmaak als koppelingen waar ze op kunnen klikken. Het stilmaken van een koppeling als cursief, kan bijvoorbeeld het feit dat de tekst een koppeling is, verdoezelen. 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 function.json-bestand 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 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

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.