Modificare un articolo della documentazione nel browser

  • 5 minuti

Ora che si dispone di una panoramica degli strumenti generali e degli elementi che operano dietro le quinte di un contributo, verranno esaminati i passaggi specifici per fornire un contributo secondario alla documentazione Microsoft. Quando si vuole apportare una piccola modifica a un articolo, assicurarsi prima di tutto di avere gli strumenti appropriati configurati. Quindi, si potrà iniziare a modificare e condividere le proprie conoscenze con altri membri della community di Microsoft Learn.

Passaggio 1: Configurare l'account GitHub

Poiché Microsoft Learn integra i flussi di lavoro di GitHub per aggiornare il contenuto, è necessario un account GitHub per contribuire. Se si ha già un account GitHub, assicurarsi di aver eseguito l'accesso.

Se non si ha ancora un account GitHub, seguire questa procedura per crearne uno:

  1. Passare a GitHub.
  2. Selezionare Iscriviti.
  3. Seguire le istruzioni per configurare l'account.

Passaggio 2: Apportare le modifiche

Tenere presente che non tutti i contenuti di Microsoft Learn vengono archiviati in un repository pubblico. Prima di apportare modifiche, verificare prima di tutto se il contenuto a cui si vuole contribuire è disponibile per il contributo pubblico. In tal caso, è possibile apportare modifiche direttamente nel browser.

  1. Passare all'articolo della documentazione su learn.microsoft.com che si desidera modificare. Controllare se l'articolo è archiviato in un repository pubblico cercando l'icona a forma di matita Modifica posta nella parte superiore dell'articolo. Se viene visualizzata l'icona, l'articolo è idoneo per il contributo pubblico.

  2. Selezionare Modifica (icona matita). Verrà visualizzato il file di origine nel repository GitHub pubblico in cui è archiviato l'articolo.

    Screenshot di un articolo della documentazione di Microsoft Learn con l'icona di modifica a forma di matita evidenziata.

  3. Selezionare l'icona a forma di matita nella parte superiore della pagina del file GitHub. Questa icona è etichettata Modificare il file nel fork di questo progetto o Creare una copia tramite fork di questo repository e modificare il file, a seconda che sia già stato creato il fork del repository in cui è archiviato il file.

    A questo punto è necessario accedere all'account GitHub per selezionare questa icona. Se non è stato eseguito l'accesso, questa opzione non è disponibile.

    Screenshot del file di origine GitHub per un articolo della documentazione. L'icona a forma di matita Modifica file è evidenziata.

    Nella parte superiore dell'articolo si noteranno 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.

  4. Se questa è la prima volta che si lavora in questo repository, viene richiesto di creare una copia tramite fork del repository prima di proporre modifiche. In tal caso, selezionare Crea una copia del repository tramite fork.

  5. Nel browser verrà visualizzata l'interfaccia di modifica o il riquadro Modifica. È possibile visualizzare l'articolo scritto in Markdown, una sintassi di formattazione. Apportare le modifiche nel riquadro.

    Screenshot di un browser con un articolo della documentazione scritto nella sintassi markdown, che può essere modificato nel riquadro Modifica.

  6. Nella parte superiore del riquadro di modifica, selezionare la scheda Anteprima. In questo modo, è possibile convalidare le modifiche visualizzandole nel modulo pubblicato.

Passaggio 3: Creare la richiesta pull

Al termine dell'esecuzione e della visualizzazione in anteprima delle modifiche, è possibile creare la richiesta pull. Tenere presente che una richiesta pull è il modo per proporre che le modifiche vengano unite al ramo principale del repository live per diventare visibili su Microsoft Learn. Una richiesta pull PR abilita il modello di collaborazione di GitHub, chiedendo che venga eseguito il pull delle modifiche del ramo di lavoro dell'utente per poi unirle a un altro ramo. Nella maggior parte dei casi, questo altro ramo è quello predefinito nel repository principale.

  1. Trovare e selezionare il pulsante Commit delle modifiche o Proponi modifiche, in genere posizionato nella parte superiore della pagina.

  2. Immettere un Messaggio di commit. Questo diventerà il titolo della richiesta pull. Il messaggio di commit deve contenere un breve riepilogo delle modifiche. Facoltativamente, aggiungere una Descrizione estesa per fornire ulteriori dettagli sulle modifiche.

    Screenshot della casella popup con due campi per creare un messaggio di commit e aggiungere una descrizione estesa delle modifiche.

  3. Selezionare Proponi modifiche.

  4. Nella pagina successiva, viene chiesto di verificare la posizione in cui unire le modifiche, denominate la base. Confermare che la base sia main.

    Screenshot della pagina Web in cui i collaboratori devono verificare il repository di destinazione e il ramo in cui si vogliono unire le modifiche. Principale è selezionato come Base.

  5. Selezionare Crea richiesta pull.

  6. Visualizzare in anteprima la richiesta pull. Apportare modifiche ai campi titolo o descrizione.

  7. Selezionare il pulsante Crea richiesta pull. Verrà aperta la richiesta pull.

La richiesta pull è stata creata, ma non è ancora stata inviata. Nel passaggio successivo, si completeranno i passaggi di verifica finali della richiesta pull per unirla.

Scenario: Modificare un articolo del servizio App di Azure

Tenere presente che si è un software engineer con competenze speciali nel servizio app di Azure. Quando si esamina un articolo della documentazione sul servizio app, si noterà un dettaglio che si vuole aggiungere per consentire ad altri utenti di usare il servizio. Si decide quindi di condividere le proprie conoscenze apportando il primo contributo a Microsoft Learn. Dopo aver eseguito l'accesso all'account GitHub, avviare il processo del contributo: