Panoramica della guida per i collaboratori della documentazione di Microsoft Learn

Benvenuti nella guida ai collaboratori alla documentazione di Microsoft Learn!

Condividere le proprie competenze con altri utenti in Microsoft Learn aiuta tutti a raggiungere di più. Usare le informazioni contenute in questa guida per pubblicare un nuovo articolo in Microsoft Learn o apportare aggiornamenti a un articolo pubblicato esistente.

Diversi set di documentazione Microsoft sono open source e ospitati in GitHub. Non tutti i set di documenti sono completamente open source, ma molti hanno repos pubblici in cui è possibile suggerire modifiche tramite richieste pull (PR). Questo approccio open source semplifica e migliora la comunicazione tra i tecnici del prodotto, i team di contenuto e i clienti e offre altri vantaggi:

  • Il piano di repos open source è aperto per ottenere commenti e suggerimenti su quali documenti sono più necessari.
  • Revisione dei repos open source aperta per pubblicare il contenuto più utile nella prima versione.
  • Aggiornamento dei repos open source all'aperto per semplificare il miglioramento continuo del contenuto.

L'esperienza utente in Microsoft Learn integra i flussi di lavoro di GitHub direttamente per semplificare ulteriormente. Iniziare modificando il documento visualizzato. In alternativa, esaminare nuovi argomenti o creare problemi di qualità.

Importante

Tutti i repository che pubblicano in Microsoft Learn hanno adottato il codice di comportamento Microsoft Open Source o il codice di comportamento di .NET Foundation. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) Contatta opencode@microsoft.com o con eventuali domande o conduct@dotnetfoundation.org commenti.

Le correzioni o i chiarimenti secondari alla documentazione e agli esempi di codice nei repository pubblici sono coperti dalle condizioni di utilizzo learn.microsoft.com. Le modifiche nuove o significative generano un commento nella richiesta richiesta di invio di un contratto di licenza di contributo online (CLA) se non si è un dipendente Microsoft. È necessario completare il modulo online prima di poter esaminare o accettare la richiesta richiesta.

Modifiche rapide alla documentazione

Le modifiche rapide semplificano il processo per segnalare e correggere piccoli errori ed omissioni nella documentazione. Nonostante l'impegno, nei documenti pubblicati si possono riscontrare piccoli errori grammaticali e ortografici. Anche se è possibile creare problemi per segnalare errori, è più veloce e più facile creare una richiesta di richiesta per risolvere il problema, quando l'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. La scelta del pulsante Modifica (o localizzata in modo equivalente) consente di accedere al file di origine in GitHub.

    Posizione del collegamento modifica articolo.

    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 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 fork e modifica matita.

  3. Modificare il file nell'editor Web. Scegliere la scheda Anteprima per controllare la formattazione delle modifiche.

  4. Al termine della modifica, scorrere fino alla fine della pagina. Nell'area Proporre modifiche immettere un titolo e facoltativamente una descrizione per le modifiche. Il titolo sarà la prima riga del messaggio di commit. Selezionare Propone modifiche per eseguire il commit delle modifiche:

    Proporre e eseguire il commit delle modifiche ai file.

  5. Dopo aver proposto e eseguito il commit delle modifiche, è necessario chiedere ai proprietari del repository di eseguire il pull delle modifiche nel repository. Questa operazione viene eseguita usando qualcosa denominato "richiesta pull" (PR). Quando si seleziona Propone modifiche, viene visualizzata una nuova pagina simile alla seguente:

    Confrontare le modifiche e creare una richiesta pull.

    Selezionare Create pull request (Crea richiesta pull). Immettere quindi un titolo e una descrizione per la richiesta pr e quindi selezionare Crea richiesta pull. Se non si ha familiarità con GitHub, vedere Informazioni sulle richieste pull per altre informazioni.

  6. L'operazione è terminata. I membri del team di contenuto esamineranno la richiesta di richiesta e lo unioneranno al momento dell'approvazione. È possibile ottenere commenti e suggerimenti che richiedono modifiche.

L'interfaccia utente di modifica di GitHub è diversa a seconda delle autorizzazioni per il repository. Le immagini precedenti sono destinate ai collaboratori che non dispongono delle autorizzazioni di scrittura nel repository di destinazione. GitHub crea automaticamente un fork del repository di destinazione nell'account. Il nome del fork appena creato ha il modulo GitHubUsername/RepositoryName per impostazione predefinita. Se si dispone dell'accesso in scrittura al repository di destinazione, ad esempio il fork, GitHub crea un nuovo ramo nel repository di destinazione. Il nome del ramo ha la patchn del modulo predefinita usando un identificatore numerico per il ramo patch.

Vengono usate le richieste per tutte le modifiche, anche per i collaboratori che dispongono dell'accesso in scrittura. La maggior parte dei repository protegge il ramo predefinito in modo che gli aggiornamenti devono essere inviati come richieste di disponibilità.

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 fornire commenti e suggerimenti sul contenuto localizzato, usare il modello di posta elettronica disponibile in aka.ms/DocSiteLocFeedback.

Esaminare le richieste pull aperte

È possibile leggere nuovi argomenti prima che vengano pubblicati controllando la coda di richiesta richiesta aperta. 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 uno dei repository di Microsoft Learn e controllare le richieste aperte per le aree che interessano l'utente. 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 hanno una sezione Feedback nella parte inferiore della pagina in cui è possibile scegliere di lasciare commenti e suggerimenti sul prodotto o commenti sui contenuti per tenere traccia dei problemi specifici di tale articolo.

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 di questa guida consentono di iniziare a contribuire in modo produttivo a Microsoft Learn. Spiegano l'uso dei repository GitHub, degli strumenti Markdown e delle estensioni usati nel contenuto di Microsoft Learn.