Condividi tramite

Elenco di controllo dell'editor

Questo articolo contiene un elenco riepilogato di regole per la scrittura o la modifica della documentazione di PowerShell. Per spiegazioni dettagliate ed esempi di queste regole, vedere altri articoli nella Guida per i collaboratori.

Metadati

  • ms.date: deve essere nel formato MM/GG/AAAAA
    • Modificare la data in cui è presente un aggiornamento significativo o effettivo
      • Riorganizzazione dell'articolo
      • Correzione degli errori effettivi
      • Aggiunta di nuove informazioni
    • Non modificare la data se l'aggiornamento non è significativo
      • Correzione di errori di digitazione e formattazione
  • title: stringa univoca di lunghezza compresa tra 43 e 59 caratteri (inclusi gli spazi)
    • Non includere l'identificatore del sito (generato automaticamente)
    • Usare la distinzione tra maiuscole e minuscole: usare solo la prima parola e tutti i sostantivi appropriati
  • description: 115-145 caratteri, inclusi gli spazi: questa astrazione viene visualizzata nel risultato della ricerca

Formattazione

  • Elementi della sintassi backtick che appaiono in linea all'interno di un paragrafo
    • Nomi dei cmdlet Verb-Noun
    • Variabile $counter
    • Esempi sintattici Verb-Noun -Parameter
    • Percorsi di file C:\Program Files\PowerShell, /usr/bin/pwsh
    • URL che non devono essere selezionabili nel documento
    • Valori di proprietà o parametri
  • Usare il grassetto per i nomi delle proprietà, i nomi dei parametri, i nomi di classe, i nomi dei moduli, i nomi di entità, l'oggetto o i nomi dei tipi
    • Il grassetto viene usato per il markup semantico, non per l'enfasi
    • Grassetto: usare gli asterischi **
  • Corsivo: usare il carattere di sottolineatura _
    • Usato solo per enfasi, non per il markup semantico
  • Interruzioni di riga a 100 colonne (o a 80 per about_Topics)
  • Nessuna scheda rigida: usare solo spazi
  • Nessuno spazio alla fine delle righe
  • Le parole chiave e gli operatori di PowerShell devono essere tutti minuscoli
  • Usare la forma corretta (Pascal casing) per i nomi e i parametri dei cmdlet

Intestazioni

  • Iniziare con H1 per primo- un solo H1 per articolo
  • Usare solo intestazioni ATX
  • Usare la distinzione tra maiuscole e minuscole per tutte le intestazioni
  • Non saltare i livelli - nessun H3 senza H2
  • Limitare la profondità dell'intestazione a H3 o H4
  • Aggiungere righe vuote prima e dopo
  • Non aggiungere o rimuovere intestazioni: PlatyPS applica intestazioni specifiche nel relativo schema

Blocchi di codice

  • Aggiungere righe vuote prima e dopo
  • Usare delimitazioni di codice con tag - PowerShell, Output o altro ID lingua appropriato
  • Usare un recinto di codice senza tag per i blocchi di sintassi
  • Inserire l'output in un blocco di codice separato, ad eccezione degli esempi di base in cui non si intende che il lettore usi il pulsante Copia
  • Vedere l'elenco delle lingue supportate

Elenchi

  • Rientro corretto
  • Aggiungere righe vuote prima del primo elemento e dopo l'ultimo elemento
  • Usare il trattino (-) non gli asterischi (*) per i punti elenco, per ridurre la confusione con l'enfasi.
  • Usare 1. per tutti gli elementi in un elenco numerato

Terminologia

Esempi di riferimento sui cmdlet

  • Deve avere almeno un esempio nel riferimento ai cmdlet

  • Gli esempi devono essere solo codice sufficiente per illustrare l'utilizzo

  • Sintassi di Powershell

    • Usare nomi completi di cmdlet e parametri, senza alias
    • Usare lo splatting per i parametri quando la riga di comando diventa troppo lunga
    • Evitare di utilizzare i backtick per la continuazione delle righe, utilizzarli solo quando strettamente necessario.

  • Rimuovere o semplificare il prompt di PowerShell (PS>) tranne se necessario per l'esempio

  • L'esempio di riferimento del cmdlet deve seguire lo schema PlatyPS seguente

    ### Example 1 - Descriptive title

Zero or more short descriptive paragraphs explaining the context of the example followed by one or
more code blocks. Recommend at least one and no more than two.

```powershell
... one or more PowerShell code statements ...
```

```Output
Example output of the code above.
```

Zero or more optional follow up paragraphs that explain the details of the code and output.

  • non inserire paragrafi tra i blocchi di codice. Tutto il contenuto descrittivo deve provenire prima o dopo i blocchi di codice.

Collegamento ad altri documenti

  • Quando si collega al di fuori del set di documenti o tra i riferimenti ai cmdlet e quelli concettuali
    • Usare GLI URL relativi al sito quando si esegue il collegamento a Microsoft Learn (rimuovere https://learn.microsoft.com/en-us)
    • non includere localizzazioni negli URL delle proprietà Microsoft (rimuovere /en-us dall'URL)
    • Tutti gli URL ai siti Web esterni devono usare HTTPS a meno che non sia valido per il sito di destinazione
  • Quando si esegue il collegamento all'interno del docset
    • Usare il percorso file relativo (../folder/file.md)
  • Tutti i percorsi usano caratteri barra in avanti (/)
  • I collegamenti immagine devono avere testo alternativo univoco
  • Last updated on