Condividi tramite

Linee guida per la formattazione del testo

L'uso coerente e appropriato degli stili grassetto e corsivo e dello stile codice per gli elementi di testo migliora la leggibilità e la chiarezza del testo. Se un elemento di formattazione del testo non è coperto da queste linee guida, fare riferimento alla Guida di stile di scrittura Microsoft. Gli articoli seguenti forniscono indicazioni dettagliate sulla formattazione del testo:

Elementi di interfaccia utente

Gli elementi dell'interfaccia utente, ad esempio voci di menu, nomi di dialogo e nomi di caselle di testo, devono essere in grassetto.

  • InEsplora soluzioni fare clic con il pulsante destro del mouse sul nodo del progetto e quindi scegliere Aggiungi>nuovo elemento.

  • Non questo: in Esplora soluzioni fare clic con il pulsante destro del mouse sul nodo del progetto e quindi scegliere Aggiungi > nuovo elemento.

Repository Git e nomi di ramo

Usare il testo in grassetto per i nomi dei repository Git o dei rami quando selezionati o immessi nelle istruzioni.

  • Questo: dal menu del ramo selezionare main.

  • Non questo: dal menu del ramo selezionare "main".

Introduzione a nuovi termini

Usare il testo in corsivo per introdurre un nuovo termine insieme a una definizione o una spiegazione. Mettete in corsivo il nuovo termine la prima volta che lo usate, e poi utilizzate il testo normale per la definizione o la spiegazione.

  • Usare: Nel servizio app un'app viene eseguita in un piano di servizio app. Un piano di servizio app definisce un set di risorse di calcolo per l'esecuzione di un'app Web.

  • Non questo: in servizio app un'app viene eseguita in un "piano di servizio app". Un piano di servizio app definisce un set di risorse di calcolo per l'esecuzione di un'app Web.

Stile del codice

Usare lo stile di codice per:

  • Elementi di codice come i nomi dei metodi, i nomi delle proprietà e le parole chiave del linguaggio.
  • Comandi SQL
  • Nomi dei pacchetti NuGet
  • Comandi della riga di comando*
  • Nomi di tabelle e colonne di database
  • Nomi di risorse che non devono essere localizzati, come i nomi delle macchine virtuali
  • URL da rendere non selezionabili

Perché? Alcune guide di stile specificano il grassetto per molti di questi elementi di testo. La maggior parte degli articoli viene tuttavia localizzata e lo stile di codice indica al traduttore di lasciare invariata la specifica parte del testo.

Lo stile del codice può essere inline (racchiuso tra ') oblocchi di codice delimitati (racchiusi da ''') che si estendono su più righe. È consigliabile inserire gli snippet di codice e i percorsi lunghi in blocchi di codice delimitati.

* Nei comandi della riga di comando usare le barre nei percorsi dei file se sono supportate in tutte le piattaforme. Usare le barre rovesciata per illustrare i comandi eseguiti in Windows, quando sono supportate solo le barre rovesciata. Ad esempio, le barre funzionano nell'interfaccia della riga di comando di .NET in tutte le piattaforme, quindi è consigliabile usare dotnet build foldername/filename.csproj anziché dotnet build foldername\filename.csproj.

Esempi d'uso di stili inline

  • Usare: Per impostazione predefinita, Entity Framework interpreta una proprietà denominata Id o ClassnameID come la chiave primaria.
  • Non usare: Per impostazione predefinita, Entity Framework interpreta una proprietà denominata Id o ClassnameID come la chiave primaria.
  • Usare: Il pacchetto Microsoft.EntityFrameworkCore garantisce il supporto runtime per EF Core.
  • Non usare: Il pacchetto Microsoft.EntityFrameworkCore garantisce il supporto runtime per EF Core.

Esempi di blocchi di codice delimitati

  • Usare: Il database non riceve nessun comando dalle istruzioni che modificano solo un elemento IQueryable, ad esempio il codice seguente:

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

  • Non questo: nessun comando viene inviato al database dalle istruzioni che modificano semplicemente un oggetto IQueryable, ad esempio var students = context. Students.Where(s => s.LastName == "Davolio").

  • Usare: Ad esempio, per eseguire lo script Get-ServiceLog.ps1 nella directory C:\Scripts digitare:

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

  • Non usare : Ad esempio, per eseguire lo script Get-ServiceLog.ps1 nella directory C:\Scripts digitare: "C:\Scripts\Get-ServiceLog.ps1."

  • Tutti i blocchi di codice delimitati devono avere un tag di linguaggio approvato. Per un elenco dei tag di linguaggio supportati, vedere Come includere codice in Docs.

Segnaposto

Nei passaggi procedurali o nel testo di paragrafo, usare il corsivo per il testo segnaposto che gli utenti sostituiranno con le proprie informazioni.

  • Questo: immettere la password

  • Non in questo modo: immettere "password"

  • Questo: immettere -ppassword

  • Non è questo: immettere -p password

Se si desidera che l'utente sostituisca parte di una stringa di input con i propri valori, usare il testo segnaposto contrassegnato da parentesi angolari (minore di < e maggiore di > caratteri).

Opzione 1: usare lo stile del codice per racchiudere la parola segnaposto o la frase che include. Ad esempio, è possibile usare i singoli backticks ' per la formattazione inline del codice per una singola frase o per la formattazione delimitata dal codice.For example, you can use single backticks ' for inline-codecoded formatting for a single phrase, or triple-ticks ''' for code-fenced formatting.

`az group delete -n <ResourceGroupName>`

Rendering eseguito come:

az group delete -n <ResourceGroupName>

o

Opzione 2: usare un carattere barra rovesciata \ per eseguire l'escape dei caratteri delle parentesi angolari in Markdown, ad esempio \< e \>. Anche se è necessaria solo la prima sequenza di escape sulla parentesi \< angolare sinistra, l'escape della parentesi chiusa \> funziona anche per coerenza. Il codice HTML sottoposto a rendering non mostra il carattere di escape al lettore:

az group delete -n \<ResourceGroupName\>

Rendering eseguito come:

az group delete -n <ResourceGroupName>

Informare il lettore del segnaposto: nel testo che precede gli esempi di segnaposto spiegare al lettore che il testo tra parentesi quadre deve essere rimosso e sostituito con valori reali. È consigliabile usare il corsivo per l'input dell'utente. È possibile formattare il corsivo all'interno di codice inline racchiuso tra parentesi angolari:

Nell'esempio seguente sostituire il testo <ResourceGroupName> segnaposto con il proprio nome del gruppo di risorse.

Attenzione

Il sito di Microsoft Learn non esegue il rendering <del testo segnaposto> che usa parentesi angolari nei casi in cui le parentesi quadre non sono precedute correttamente da escape o il testo non è formattato in codice. Il processo di compilazione di Microsoft Learn interpreta la <frase segnaposto> come tag HTML che potrebbe essere pericoloso per il browser del lettore e lo contrassegna come tag html-non consentito. Verrà visualizzato un suggerimento nel report di compilazione e il rendering della parola segnaposto non viene eseguito nell'output della pagina di Microsoft Learn in questo caso.

Per evitare la perdita di contenuto nei segnaposto, usare la formattazione o i code caratteri di escape (\<\>) come descritto in precedenza.

Non è consigliabile usare parentesi graffe { } come segnaposto sintattico. I lettori possono confondere segnaposto parentesi graffe con la stessa notazione usata in:

  • Testo sostituibile
  • Stringhe di formato
  • Interpolazione di stringa
  • Modelli di testo
  • Costrutti di programmazione simili

Maiuscole e minuscole: è possibile separare i nomi segnaposto con trattini ("maiuscolo kebab") o con caratteri di sottolineatura oppure è possibile farlo usando la combinazione di maiuscole e minuscole Pascal. Il caso kebab potrebbe generare errori di sintassi e i caratteri di sottolineatura potrebbero essere in conflitto con la sottolineatura. L'uso di tutte le lettere maiuscole può essere in conflitto con le costanti con nome in molte lingue, sebbene possa anche attirare l'attenzione sul nome del segnaposto.

<Resource-Group-Name> oppure <ResourceGroupName>

Intestazioni

Non applicare uno stile inline come corsivo, grassetto o stile di codice inline alle intestazioni.

Perché? Le intestazioni hanno stili personalizzati, e mescolare altri stili crea incoerenze.

  • This: Import the Microsoft.NET.Sdk.Functions package (Importare il pacchetto Microsoft.NET.Sdk.Functions)

  • Non è questo: importare il pacchetto Microsoft.NET.Sdk.Functions

Testo del collegamento

Non applicare lo stile inline come corsivo o grassetto per collegare il testo.

Perché? Le persone identificano gli elementi di testo come collegamenti selezionabili in base alla formattazione standard del testo del collegamento ipertestuale. Lo stile di un collegamento come corsivo, ad esempio, può nascondere il fatto che il testo è un collegamento.

Non questo: il pacchetto NuGet Microsoft.NET.Sdk.Functions genera il file function.json.

Tasti e scelte rapide da tastiera

Quando si fa riferimento a tasti o combinazioni di tasti, attenersi alle convenzioni seguenti:

  • Usare l'iniziale maiuscola per i nomi dei tasti.
  • Racchiudere i nomi delle chiavi con <kbd> i tag HTML e </kbd> .
  • Usare "+" per unire le chiavi selezionate dall'utente contemporaneamente.

Esempi di tasti e tasti di scelta rapida

  • In questo modo, selezionare ++
  • Non questo: premere ALT+CTRL+S.
  • Non è questo: premere ALT+CTRL+S.

Eccezioni

Linee guida di stile coerenti creano un'esperienza cliente affidabile e semplificano il processo di creazione. Le eccezioni a queste linee guida devono essere considerate attentamente.

Se l'eccezione prevede l'uso di uno stile di testo alternativo che normalmente chiama il codice, assicurarsi che sia ok tradurre il testo nelle versioni localizzate dell'articolo. Per gli scenari in cui si vuole impedire la localizzazione senza usare lo stile di codice, vedere Stringhe non localizzate.