Guida introduttiva ai contributi alla documentazione di PowerShellGet started contributing to PowerShell documentation

Questo articolo offre una panoramica su come contribuire alla documentazione di PowerShell.This article is an overview of how to get started as a contributor to the PowerShell documentation.

Struttura PowerShell-DocsPowerShell-Docs structure

Il repository PowerShell-Docs è suddiviso in due gruppi di contenuti.The PowerShell-Docs repository is divided into two groups of content. Per gestire la modalità e il momento in cui la documentazione viene pubblicata vengono usati i rami Git.Git branches are used to manage how and when documentation gets published.

Contenuto di riferimentoReference content

Il contenuto di riferimento è il riferimento dei cmdlet di PowerShell per i cmdlet inclusi in PowerShell.The reference content is the PowerShell cmdlet reference for the cmdlets that ship in PowerShell. Il riferimento viene raccolto nelle cartelle delle versioni, 5.1, 6, 7.0 e 7.1.The reference is collected in versions folders (5.1, 6, 7.0, and 7.1). Questo contenuto raccoglie solo il riferimento dei cmdlet per i moduli inclusi in PowerShell.This content contains cmdlet reference only for the modules that ship with PowerShell. Viene usato anche per creare le informazioni della Guida visualizzate dal cmdlet Get-Help.This content is also used to create the help information displayed by the Get-Help cmdlet.

Nota

Il sommario del contenuto di riferimento viene generato automaticamente dal sistema di pubblicazione.The Table of Contents (TOC) for reference content is autogenerated by the publishing system. Non è necessario aggiornarlo.You don't have to update the TOC.

Contenuto concettualeConceptual content

La documentazione concettuale include i contenuti seguenti:The conceptual documentation includes the following content:

  • Note sulla versioneRelease notes
  • Istruzioni di configurazioneSetup instructions
  • Script di esempio e procedure dettagliateSample scripts and how-to articles
  • Documentazione DSCDSC documentation
  • Documentazione SDKSDK documentation

La documentazione concettuale non è organizzata in base alla versione.The conceptual documentation is not organized by version. Tutti gli articoli vengono visualizzati per ogni versione di PowerShell.All articles are displayed for every version of PowerShell. Stiamo lavorando per creare articoli specifici per versione.We are working to create version-specific articles. Questa guida verrà aggiornata con le informazioni appropriate quando la funzionalità sarà disponibile nella documentazione.When that feature is available in our documentation, this guide will be update with the appropriate information.

Nota

Ogni volta che un articolo concettuale viene aggiunto, rimosso o rinominato, il sommario deve essere aggiornato e incluso nella richiesta pull.Anytime a conceptual article is added, removed, or renamed, the TOC must be updated and included in the pull request.

Uso dei rami GitUsing git branches

Il ramo predefinito per PowerShell-Docs è il ramo staging.The default branch for PowerShell-Docs is the staging branch. Le modifiche apportate ai rami di lavoro vengono uniti al ramo staging prima di essere pubblicate.Changes made in working branches are merged into the staging branch before then being published. All'incirca una volta alla settimana il ramo staging viene unito al ramo live.About once a week, the staging branch is merged into the live branch. Il ramo live include il contenuto pubblicato in docs.microsoft.com.The live branch contains the content that is published to docs.microsoft.com. Le modifiche non devono mai essere apportate direttamente nel ramo live.Changes should never be made directly in the live branch.

Se si sta inviando una modifica alla documentazione che si applica solo a una versione non rilasciata di PowerShell, verificare se esiste un ramo di rilascio per tale versione.If you are submitting a change to documentation that only applies to an unreleased version of PowerShell, check to see if there is a release branch for that version. Tutte le modifiche che si applicano a una versione futura specifica devono essere destinate al ramo di rilascio.All changes that apply to a specific, future version should be targeted at the release branch. I rami di rilascio hanno il seguente modello di denominazione: release-<version>.Release branches have the following name pattern: release-<version>.

Prima di iniziare ad apportare qualsiasi modifica, creare un ramo di lavoro nella copia locale del repository PowerShell-Docs.Before starting any changes, create a working branch in your local copy of the PowerShell-Docs repository. La copia tramite fork deve essere come illustrato.This should be a clone of your fork. Assicurarsi di sincronizzare il repository locale prima di creare il ramo di lavoro.Be sure to synchronize your local repository before creating your working branch. Il ramo di lavoro deve essere creato da una copia da aggiornamento a data del ramo staging o release.The working branch should be created from an update-to-date copy of the staging or release branch.

Apportare le modifiche dopo il processo nella sezione Apportare le modifiche della guida per i contributi.Make the changes you want to submit following the process in the Making your change section of the central Contributor's Guide.

Creazione di nuovi articoliCreating new articles

Per ogni nuovo documento con cui si vuole contribuire è necessario creare un problema di GitHub.A GitHub issue must be created for any new document you want to contribute. Verificare i problemi esistenti per assicurarsi di non inserire problemi duplicati.Check for existing issues to make sure you're not duplicating efforts. I problemi assegnati a un utente sono considerati "in corso".Issues that are assigned to someone are considered to be "in progress". Se si vuole collaborare a un problema, contattare la persona assegnata al problema.If you wish to collaborate on an issue, contact the person assigned to the issue.

In modo analogo al processo di RFC di PowerShell, creare un problema prima di scrivere il contenuto consente di evitare di lavorare su un elemento che viene poi rifiutato dal team di PowerShell-Docs.Similar to the PowerShell RFC process, creating an issue before writing the content ensures that you don't spend a lot of time and effort on something that gets rejected by the PowerShell-Docs team. Questo consente anche al team di consultare l'utente in merito all'ambito del contenuto e al suo posizionamento nella documentazione di PowerShell.This also allows us to consult with you on the scope of the content and where it should fit within the PowerShell documentation.

Aggiornamento di articoli esistentiUpdating existing articles

Laddove possibile, gli articoli dei riferimenti dei cmdlet vengono duplicati in tutte le versioni di PowerShell.Where applicable, cmdlet reference article are duplicated across all versions of PowerShell. Quando si segnala un problema relativo a un riferimento di un cmdlet o a un articolo About_, è necessario specificare quali versioni sono interessate dal problema.When reporting an issue about a cmdlet reference or an About_ article, you must specify which versions are affected by the issue. Il modello di problema in GitHub include un elenco di controllo delle versioni.The issue template in GitHub includes a checklist of versions. Usare le caselle di controllo per specificare le versioni del contenuto interessate.Use the checkboxes to specify which versions of the content are affected. Quando si invia una modifica a un articolo per un problema che interessa più versioni del contenuto, è necessario applicare la modifica appropriata a ogni versione del file.When you submit a change to a article for an issue that affects multiple versions of the content, you must apply the appropriate change to each version of the file.

Passaggi successiviNext steps

Vedere Invio di una richiesta pullSee Submitting a pull request