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. Se il pulsante Modifica non è disponibile, ciò indica che la pagina della documentazione non è disponibile per la modifica.

    Percorso del collegamento Modifica

    Se il pulsante Modifica non viene visualizzato significa che il contenuto non è aperto ai contributi pubblici.

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

    Posizione dell'icona a forma di matita

  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 (Proponi modifica file)

  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 Propose file change (Proponi modifica file), viene visualizzata una nuova pagina simile alla seguente:

    creare una richiesta pull

    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 di nuovo github, vedere Informazioni sulle richieste pull per altre informazioni.

  6. Questo è tutto. I membri del team del contenuto rivedranno e uniranno la richiesta pull una volta approvata. È 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, che usa l'ID GitHub e un identificatore numerico per il ramo della 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 tramite GitHub. Per inviare commenti e suggerimenti sul contenuto localizzato, usare il modello di posta elettronica disponibile all'aka.ms/DocSiteLocFeedback. Esiste un'eccezione per la documentazione di Azure. Sono disponibili repository GitHub localizzati pubblici per azure-docs aperti per il contributo della community per 6 lingue: cinese semplificato, francese, tedesco, giapponese, coreano e spagnolo. Per tutte le altre lingue e i set di contenuti, usare il modello di posta elettronica, che riceve l'input in qualsiasi lingua, per segnalare problemi di traduzione o per inviare commenti e suggerimenti tecnici.

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.