Panoramica della guida per i collaboratori di Microsoft Docs

Questa è la Guida per i collaboratori di docs.microsoft.com.

Diversi set di documentazione Microsoft sono open source e ospitati in GitHub. Non tutti i set di documenti sono completamente open source, ma per molti sono disponibili repository pubblici dove è possibile suggerire modifiche tramite richieste pull. Questo approccio open source semplifica e migliora la comunicazione tra i progettisti del prodotto, i team dei contenuti e i clienti, oltre a offrire altri vantaggi:

  • La pianificazione dei repository open source è visibile per poter ricevere commenti e suggerimenti sugli argomenti che più necessitano di documentazione.
  • La revisione dei repository open source è visibile per poter pubblicare il contenuto più utile già nella prima versione.
  • Gli aggiornamenti dei repository open source sono visibili per poter migliorare costantemente il contenuto con facilità.

L'esperienza utente in docs.microsoft.com viene direttamente integrata con i flussi di lavoro di GitHub così da risultare ancora più semplice. È possibile iniziare modificando il documento visualizzato, dare un contributo revisionando i nuovi argomenti o segnalare problemi di qualità elevata.

Importante

Tutti i repository che pubblicano contenuto in docs.microsoft.com adottano il Microsoft Open Source Code of Conduct (Codice di comportamento Open Source di Microsoft) o il .NET Foundation Code of Conduct (Codice di comportamento di .NET Foundation). Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com o conduct@dotnetfoundation.org per eventuali domande o commenti.

Le correzioni minori o i chiarimenti inviati per la documentazione e gli esempi di codice nei repository pubblici sono coperti dalle Condizioni per l'utilizzo di docs.microsoft.com. Per le novità o le modifiche significative viene generato un commento nella richiesta pull con la richiesta di inviare un contratto di licenza online per contributi se non si è dipendenti Microsoft. Prima che la richiesta pull venga esaminata o accettata, è necessario completare il modulo online.

Modifiche rapide ai documenti esistenti

Le modifiche rapide semplificano il processo di segnalazione e correzione di piccoli errori e omissioni. Nonostante l'impegno, nei documenti pubblicati si possono riscontrare piccoli errori grammaticali e ortografici. Anche se è possibile segnalare problemi per informare di errori, è più facile e veloce creare una richiesta pull per risolvere il problema, quando questa opzione è disponibile.

  1. Alcune pagine della documentazione consentono di modificare il contenuto direttamente nel browser. In questo caso, sarà visualizzato un pulsante Modifica come quello mostrato di seguito. Facendo clic sul pulsante Edit (o sulla versione equivalente localizzata) si accede al file di origine in GitHub.

    Location of the Edit link

    Se il pulsante Modifica non è presente, significa che il contenuto non è aperto ai contributi pubblici. Alcune pagine vengono generate (ad esempio, dalla documentazione inline nel codice) e devono essere modificate nel progetto a cui appartengono.

  2. Selezionare l'icona della matita per modificare l'articolo. Se l'icona a forma di matita è inattiva, è necessario accedere all'account GitHub o crearne uno nuovo.

    Location of the pencil icon

  3. Apportare modifiche nell'editor Web. Fare clic sulla scheda Preview changes (Anteprima modifiche) per controllare la formattazione della modifica.

  4. Dopo avere apportato le modifiche, scorrere fino alla fine della pagina. Immettere un titolo e una descrizione per le modifiche e fare clic su Propose file change (Proponi modifica file), come illustrato nella figura seguente:

    Propose file change

  5. Dopo aver proposto la modifica, è necessario chiedere ai proprietari del repository di eseguire il "pull" delle modifiche nel loro repository. Questa operazione viene eseguita tramite una "richiesta pull". Quando si seleziona Proponi modifica file,viene visualizzata una nuova pagina simile alla seguente:

    create pull request

    Selezionare Crea richiesta pull,immettere un titolo e facoltativamente una descrizione per la richiesta pull e quindi selezionare Crea richiesta pull. Se non si ha GitHub, vedere Informazioni sulle richieste pull per altre informazioni.

  6. Questo è tutto. I membri del team di contenuti rivedranno e uniranno le richieste pull quando verranno approvate. È possibile ricevere commenti e suggerimenti che richiedono modifiche.

L'interfaccia utente di modifica di GitHub è diversa a seconda delle autorizzazioni per il repository. Le immagini precedenti si riferiscono a collaboratori che non hanno autorizzazioni di scrittura per il repository di destinazione. GitHub crea automaticamente un fork del repository di destinazione nell'account. Se si ha l'accesso in scrittura al repository di destinazione, GitHub crea una nuovo ramo nel repository di destinazione. Il nome del ramo ha il formato GitHubId > -patch-n usando l'ID GitHub e un identificatore numerico per il ramo patch.

Le richieste pull vengono usate per tutte le modifiche, anche per i collaboratori che hanno l'accesso in scrittura. La maggior parte dei repository ha il ramo predefinito protetto in modo che gli aggiornamenti devono essere inviati come richieste pull.

L'esperienza di modifica nel browser è ideale per modifiche secondarie o poco frequenti. Per pubblicare contributi più estesi oppure se si usano funzionalità Git avanzate, come la gestione dei rami o la risoluzione avanzata dei conflitti di merge, è necessario creare una copia tramite fork del repository e lavorare in locale.

Nota

La maggior parte della documentazione localizzata non offre la possibilità di modificare o fornire commenti e suggerimenti GitHub. Per inviare commenti e suggerimenti sul contenuto localizzato, usare il modello di posta elettronica disponibile in aka.ms/DocSiteLocFeedback.

Esaminare le richieste pull aperte

Per leggere i nuovi argomenti prima che vengano pubblicati, è possibile controllare le richieste pull attualmente aperte. Le revisioni seguono il processo del flusso GitHub. È possibile visualizzare gli aggiornamenti proposti o i nuovi articoli nei repository pubblici. Esaminarli e aggiungere i commenti. Esaminare i repository di documenti e controllare le richieste pull aperte per le aree a cui si è interessati. I commenti e suggerimenti della community sugli aggiornamenti proposti sono utili all'intera community.

Segnalare problemi di qualità

I documenti vengono continuamente rielaborati. La corretta formulazione dei problemi consente a Microsoft di impegnarsi maggiormente sulle priorità principali della community. Specificare il maggior numero possibile di dettagli. In questo modo la segnalazione sarà più utile. Indicare le informazioni cercate. Indicare i termini di ricerca usati. Se non si riesce a iniziare, spiegare come si vuole iniziare a esplorare una tecnologia con cui non si ha familiarità.

Molte delle pagine della documentazione di Microsoft includono una sezione Commenti nella parte inferiore, in cui è possibile fare clic per inviare Commenti sul prodotto oppure Commenti sul contenuto per registrare segnalazioni specifiche per l'articolo in questione.

Le segnalazioni danno avvio a una conversazione su ciò che è necessario. Il team dei contenuti risponderà a queste segnalazioni elencando le idee su ciò che è possibile aggiungere e chiederà l'opinione dell'utente. Quando viene creata una bozza, viene chiesto all'utente di esaminare la richiesta pull.

Maggiore coinvolgimento

Altri argomenti consentono di iniziare a contribuire concretamente a Microsoft Docs. Questi argomenti illustrano l'uso dei repository GitHub, gli strumenti Markdown e le estensioni usate nella piattaforma Microsoft Docs.