Condividi tramite

Contribuire ai miglioramenti qualitativi

Non è necessario essere un esperto di materia o un esperto di documentazione per contribuire. Se viene visualizzata l'opportunità di migliorare la documentazione, inviare una richiesta pull con il miglioramento proposto. Questa guida illustra diversi modi semplici in cui chiunque può contribuire ai miglioramenti qualitativi per la documentazione.

Ci concentriamo su queste aree di qualità:

Esempi di codice di formattazione

Tutti gli esempi di codice devono seguire le linee guida di stile per il contenuto di PowerShell. Tali regole vengono ripetute in formato abbreviato qui per praticità:

  • Tutti i blocchi di codice devono essere contenuti in un delimitatore di codice a tre backtick (```).
  • La lunghezza della riga per i blocchi di codice è limitata ai 90 caratteri per gli articoli di riferimento sui cmdlet.
  • La lunghezza della riga per i blocchi di codice è limitata ai 76 caratteri per about_* gli articoli.
  • Evitare di usare i caratteri di continuazione riga (`) negli esempi di codice di PowerShell.
    • Usare opportunità di splatting o interruzioni di riga naturali, come dopo i caratteri pipe (|), le parentesi graffe di apertura (}), le parentesi (() e le parentesi quadre ([) per limitare la lunghezza della riga.
  • Includere solo il prompt di PowerShell come esempio illustrativo quando il codice non è destinato al copia e incolla.
  • Non usare alias negli esempi, a meno che non si stia documentando specificamente l'alias.
  • Evitare di usare parametri posizionali. Usare il nome del parametro, anche se il parametro è posizionale.

Formattazione della sintassi dei comandi

Tutti i testi devono seguire le linee guida di stile per il contenuto di PowerShell. Queste regole vengono ripetute qui per praticità:

  • Usare sempre il nome completo per i cmdlet e i parametri. Evitare di usare alias, a meno che non si stia dimostrando specificamente l'alias.
  • Proprietà, parametro, oggetto, nomi dei tipi, nomi di classe, metodi di classe devono essere in grassetto.
    • I valori delle proprietà e dei parametri devono essere racchiusi in backticks (`).
    • Quando si fa riferimento a tipi usando lo stile tra parentesi quadre, usare i backtick. Ad esempio: [System.Io.FileInfo]
  • I nomi dei moduli di PowerShell devono essere in grassetto.
  • Le parole chiave e gli operatori di PowerShell devono essere tutti minuscoli.
  • Usare lettere maiuscole e minuscole appropriate (Pascal) per i nomi e i parametri dei cmdlet.
  • Quando si fa riferimento a un parametro in base al nome, il nome deve essere in grassetto.
  • Usare il nome del parametro con il trattino quando si illustra la sintassi. Racchiudere il parametro nei backtick.
  • Quando si mostra l'esempio di utilizzo di un comando esterno, l'esempio deve essere racchiuso tra i backtick. Includere sempre l'estensione del file del comando esterno.

Per garantire la manutenibilità e la leggibilità dei file markdown della nostra documentazione, stiamo convertendo la documentazione concettuale per utilizzare riferimenti ai collegamenti anziché i collegamenti in linea.

Ad esempio, anziché:

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

Deve essere:

The [Packages tab][01] displays all available packages in the PowerShell Gallery.

Nota

Quando si sostituisce un collegamento inline, rielaborare il contenuto per eseguire il wrapping a 100 caratteri. È possibile usare l'estensione di VS Code reflow-markdown per rielaborare rapidamente il paragrafo.

Nella parte inferiore del file aggiungere un commento markdown prima della definizione dei collegamenti.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Assicurati che:

  1. Ogni collegamento punta alla posizione corretta.
  2. Non duplicare le definizioni dei riferimenti ai collegamenti. Se esiste già una definizione di riferimento di collegamento per un URL, riutilizzare il riferimento esistente anziché crearne uno nuovo.
  3. Le definizioni di riferimento del collegamento si trovano nella parte inferiore del file dopo il commento markdown e si trovano nell'ordine numerico.

Controllo del codice Markdown

Per qualsiasi articolo in uno dei repository partecipanti, l'apertura dell'articolo in VS Code visualizza gli avvisi di linting. Risolvere tutti questi avvisi che trovi, ad eccezione di:

  • MD022/blanks-around-headings/blanks-around-headers per l'intestazione del Synopsis cmdlet nei documenti di riferimento. Per questi elementi, la violazione della regola è intenzionale per garantire che la documentazione venga compilata correttamente con PlatyPS.

Assicurarsi delle lunghezze di riga e usare l'estensione Reflow Markdown per correggere eventuali righe lunghe.

Ortografia

Nonostante i nostri migliori sforzi, gli errori di digitazione e ortografia finiscono nella documentazione. Questi errori rendono la documentazione più difficile da seguire e localizzare. La correzione di questi errori rende la documentazione più leggibile, soprattutto per i parlanti non inglesi che si basano su traduzioni accurate.

  • Last updated on