Modificare la documentazione di Microsoft Learn nel browser

  • Articolo

Suggerimento

Per questo argomento è disponibile un percorso di apprendimento rapido e dettagliato.

Diversi set di documentazione di Microsoft sono open source e ospitati in GitHub. Anche se non tutti i set di documentazione sono completamente open source, molti hanno repository pubblici in cui è possibile suggerire modifiche tramite richieste pull. Un approccio open source di questo tipo semplifica e migliora la comunicazione tra ingegneri di prodotto, team di sviluppo dei contenuti e clienti.

Le modifiche rapide facilitano il processo di segnalazione e correzione di piccoli errori e omissioni nella documentazione. Nonostante l'impegno, nei documenti pubblicati si possono riscontrare piccoli errori grammaticali e ortografici. Apprezziamo il vostro aiuto per identificare e risolvere questi problemi.

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

Prerequisito

Modificare un documento nel browser

  1. Passare alla documentazione da modificare. Alcune pagine della documentazione consentono di modificare il contenuto direttamente nel browser. In tal caso, verrà visualizzata un'icona a forma di matita Modifica come quella mostrata di seguito. La scelta dell'icona a forma di matita Modifica consente di accedere al file di origine in GitHub.

    Screenshot di un articolo della documentazione di Azure che mostra l'icona a forma di matita **Modifica**.

    Se l'icona a forma di matita 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 Modifica nella parte superiore della pagina del file GitHub. Se l'icona a forma di matita Modifica non è disponibile (visualizzata in grigio) o non viene visualizzata, è necessario accedere all'account GitHub.

    Screenshot dell'articolo di Azure all'interno di GitHub, che mostra l'icona a forma di matita **Modifica**.

    Nella parte superiore dell'articolo sono presenti i metadati dell'articolo. I metadati vengono applicati agli articoli per la creazione di report, per la scoperta attraverso la ricerca e per guidare gli aspetti dell'esperienza del sito. Se si apportano aggiornamenti secondari a un articolo pubblicato, probabilmente non sarà necessario modificare i metadati.

  3. Se è la prima volta che si lavora in questo repository, verrà richiesto di creare una copia tramite fork del repository prima di proporre modifiche. Selezionare Fork questo repository per continuare.

  4. Modificare il file nell'editor Web. Scegliere la scheda Anteprima sulla barra degli strumenti per controllare la formattazione delle modifiche.

  5. Al termine della modifica, selezionare il pulsante Commit changes (Conferma modifiche) o Propose changes (Proponi modifiche), in genere in alto a destra nella schermata.

  6. Immettere un messaggio di commit. Il messaggio di commit diventa il titolo della richiesta pull e deve essere un breve riepilogo delle modifiche(ad esempio, "Correggere gli errori ortografici e grammaticali"). Facoltativamente, aggiungere una descrizione estesa per fornire altri dettagli sulle modifiche. Selezionare Proponi modifiche:

    Screenshot del popup proporre modifiche.

  7. Dopo aver proposto ed eseguito il commit delle modifiche, è necessario chiedere ai proprietari del repository di eseguire il "pull" delle modifiche nel repository. Questa operazione viene eseguita usando una richiesta pull . Quando si seleziona Proponi modifiche, verrà visualizzata una pagina simile alla seguente:

    Screenshot della schermata di confronto delle modifiche.

    La richiesta pull propone modifiche dal fork e dal ramo (rappresentati dai due elementi a destra della freccia) nel fork principale e main nel ramo principale del repository della documentazione (rappresentato dai due elementi a sinistra della freccia).

    Esaminare le modifiche e quindi selezionare Crea richiesta pull.

  8. Nella pagina Apri una richiesta pull visualizzare in anteprima la richiesta pull. Se necessario, è possibile modificare i campi titolo o descrizione. Quando si è pronti, selezionare Crea richiesta pull. Questa azione apre la richiesta pull e avvisa il proprietario dell'articolo che hai proposto una modifica.

  9. Ecco fatto! I membri del team di contenuto esamineranno la richiesta pull e lo uniranno al momento dell'approvazione. È possibile ricevere commenti e suggerimenti che richiedono modifiche. Per altri dettagli sull'elaborazione della richiesta pull, vedere Elaborare una richiesta pull.

Limiti

  • La maggior parte dei contenuti localizzati (ovvero tradotti) non offre la possibilità di modificare tramite GitHub. Tuttavia, è possibile fornire commenti e suggerimenti sulla qualità della traduzione selezionando il pulsante Feedback (pollici) nella parte superiore della pagina e quindi scegliendo il motivo della qualità della traduzione . È anche possibile lasciare commenti e suggerimenti più specifici sui contenuti localizzati usando il modulo Invia commenti e suggerimenti .
  • L'esperienza di modifica nel browser funziona meglio per le modifiche secondarie e poco frequenti. Se si apportano contributi di grandi dimensioni o si usano funzionalità Git avanzate, ad esempio gestione dei rami o risoluzione avanzata dei conflitti di merge, è consigliabile creare una copia tramite fork del repository e lavorare in locale.