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.
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.csproj
van .
Voorbeelden met inlinestijlen
- Dit: In Entity Framework worden eigenschappen met de naam
Id
ofClassnameID
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 mapC:\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.
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor