Leggere in inglese

Condividi tramite


Contribuire alla documentazione di HoloLens

Benvenuti nella documentazione di HoloLens! Tutti gli articoli creati o modificati in questo repository saranno visibili al pubblico.

La documentazione di HoloLens è pubblicata in Microsoft Learn, che usa Markdown con funzionalità Markdig di GitHub. Il contenuto modificato in questo repository viene formattato in pagine stilizzate che vengono visualizzate in /hololens.

In questa pagina vengono illustrati i passaggi e le linee guida di base per i contributi e i collegamenti alle nozioni di base di Markdown. Grazie per il vostro contributo!

Repository disponibili

Nome repository URL
HoloLens MicrosoftDocs/HoloLens
Realtà mista MicrosoftDocs/ di realtà mista
Guida per gli appassionati di VR MicrosoftDocs/mixed-reality/enthusiast-guide

Prima di iniziare

Se non è già disponibile, è necessario creare un account GitHub.

Nota

Se si è un dipendente Microsoft, collegare l'account GitHub all'alias Microsoft nel portale Microsoft open source . Partecipa alla "Microsoft" e "MicrosoftDocs" organizzazioni.

Quando si configura l'account GitHub, è consigliabile adottare anche queste precauzioni di sicurezza:

  • Creare una password complessa per l'account GitHub.
  • Abilitare 'autenticazione a due fattori.
  • Salvare i codici di ripristino in un luogo sicuro.
  • Aggiornare le impostazioni del profilo pubblico .
    • Impostare il nome e prendere in considerazione l'impostazione del posta elettronica pubblica su Non visualizzare l'indirizzo di posta elettronica.
    • È consigliabile caricare un'immagine del profilo perché viene visualizzata un'anteprima negli articoli di Microsoft Learn a cui si contribuisce.
  • Se si prevede di usare la riga di comando, è consigliabile configurare Gestione credenziali Git per Windows. In questo modo, non sarà necessario immettere la password ogni volta che si apporta un contributo.

Il sistema di pubblicazione è associato a GitHub, quindi questi passaggi sono importanti. Verrà elencato come autore o collaboratore a ogni articolo usando l'alias GitHub.

Modifica di un articolo esistente

Usare il flusso di lavoro seguente per apportare aggiornamenti a un articolo esistente tramite GitHub in un Web browser:

  1. Passare all'articolo da modificare nella cartella "hololens".

  2. Selezionare il pulsante modifica (icona a forma di matita) in alto a destra.

    Modificare un articolo.

    In questo modo verrà eseguito automaticamente il fork di un ramo eliminabile dal ramo predefinito, principale.

  3. Modificare il contenuto dell'articolo in base alle nozioni di base Markdown.

  4. Aggiornare i metadati nella parte superiore di ogni articolo:

    • titolo: titolo della pagina visualizzato nella scheda del browser quando viene visualizzato l'articolo. I titoli di pagina vengono usati per SEO e indicizzazione, quindi non modificare il titolo a meno che non sia necessario (anche se questo è meno critico prima che la documentazione diventi pubblica).
    • descrizione: scrivere una breve descrizione del contenuto dell'articolo, che migliora seO e individuazione.
    • autore: se si è il proprietario principale della pagina, aggiungere l'alias GitHub qui.
    • ms.author: se si è il proprietario principale della pagina, aggiungere l'alias Microsoft qui (non è necessario @microsoft.com, solo l'alias).
    • ms.date: aggiornare la data se si aggiunge contenuto principale alla pagina, ma non per correzioni come chiarimento, formattazione, grammatica o ortografia.
    • parole chiave: supporto per le parole chiave in SEO (ottimizzazione del motore di ricerca). Aggiungere parole chiave, separate da una virgola e da uno spazio, specifiche dell'articolo, ma senza punteggiatura dopo l'ultima parola chiave nell'elenco. Non è necessario aggiungere parole chiave globali applicabili a tutti gli articoli, perché vengono gestite altrove.
  5. Dopo aver completato le modifiche dell'articolo, scorrere verso il basso e selezionare Proponi modifica file.

  6. Nella pagina successiva selezionare Crea richiesta pull per unire il ramo creato automaticamente nel ramo predefinito, principale .

  7. Ripetere i passaggi precedenti per l'articolo successivo da modificare.

Ridenominazione o eliminazione di un articolo esistente

Se la modifica rinomina o elimina un articolo esistente, assicurarsi di aggiungere un reindirizzamento. In questo modo, chiunque abbia un collegamento all'articolo esistente continuerà a terminare nel posto giusto. I reindirizzamenti vengono gestiti dal file .openpublishing.redirection.json nella radice del repository.

Per aggiungere un reindirizzamento a .openpublishing.redirection.json, aggiungere una voce alla matrice di redirections:

{
    "redirections": [
        {
            "source_path": "hololens/old-article",
            "redirect_url": "/base-url/new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • Il source_path è il percorso relativo del repository dell'articolo precedente che si sta rimuovendo. Assicurarsi che il percorso inizi con il docset (in questo caso, hololens) e includa l'estensione di file .md.

  • Il redirect_url è l'URL pubblico relativo dell'articolo precedente al nuovo articolo. Assicurarsi che questo URL non contenga contenere .md e inizi con /, perché fa riferimento all'URL pubblico e non al percorso del repository. È consentito il collegamento a una sezione all'interno del nuovo articolo usando #section. Se necessario, è anche possibile usare un percorso assoluto per un altro sito.

  • redirect_document_id indica se si desidera mantenere l'ID documento dal file precedente. Il valore predefinito è false. Usare true se si vuole mantenere il valore dell'attributo ms.documentid dall'articolo reindirizzato. Se si mantiene l'ID documento, i dati, ad esempio le visualizzazioni di pagina e le classificazioni, verranno trasferiti all'articolo di destinazione. Eseguire questa operazione se il reindirizzamento è principalmente una ridenominazione e non un puntatore a un articolo diverso che copre solo alcuni degli stessi contenuti.

Se si aggiunge un reindirizzamento, assicurarsi di eliminare anche il file precedente.

Creazione di un nuovo articolo

Usare il flusso di lavoro seguente per creare nuovi articoli nel repository della documentazione tramite GitHub in un Web browser:

  1. Creare un fork al di fuori del ramo predefinito, principale, di MicrosoftDocs/hololens usando il pulsante Fork in alto a destra.

    Fork il ramo predefinito, attualmente denominato

  2. Nella cartella "hololens" selezionare Crea nuovo file in alto a destra.

  3. Creare un nome di pagina per l'articolo (usare trattini invece di spazi e non usare segni di punteggiatura o apostrofi) e accodare ".md"

    Assegnare un nome alla nuova pagina.

    Importante

    Assicurarsi di creare il nuovo articolo dalla cartella "hololens". È possibile confermarlo controllando "/hololens/" nella nuova riga del nome file.

  4. Nella parte superiore della nuova pagina aggiungere il blocco di metadati seguente:

    ---
    title:
    description:
    author:
    ms.author:
    ms.date:
    ms.topic: article
    keywords:
    ---
    
  5. Compilare i campi dei metadati pertinenti come descritto in precedenza in Modifica di un articolo esistente.

  6. Scrivere contenuto dell'articolo usando le nozioni di base Markdown.

  7. Aggiungere una sezione ## See also nella parte inferiore dell'articolo con collegamenti ad altri articoli pertinenti.

  8. Al termine, selezionare Eseguire il commit di un nuovo file.

  9. Selezionare Nuova richiesta pull e unire il ramo principale fork in MicrosoftDocs/hololens principale (assicurarsi che la freccia punti alla destinazione corretta).

    Creare una richiesta pull dal fork in MicrosoftDocs/hololens.

Nozioni di base su Markdown

Le risorse seguenti consentono di apprendere come modificare la documentazione usando il linguaggio Markdown:

Aggiunta di tabelle

A causa della modalità di stile delle tabelle in Microsoft Learn, non avranno bordi o stili personalizzati, anche se si prova css inline. Sembra funzionare per un breve periodo di tempo, ma alla fine la piattaforma rimuoverà lo stile dalla tabella. Quindi pianificare in anticipo e mantenere le tabelle semplici. Ecco un sito che semplifica le tabelle Markdown: [Generatore tabelle]](https://www.tablesgenerator.com/markdown_tables).

La Docs Markdown Extension for Visual Studio Code semplifica anche la generazione di tabelle se si usa Visual Studio Code (vedere di seguito) per modificare la documentazione.

Aggiunta di immagini

Dovrai caricare le immagini nella cartella "hololens/images" nel repository e quindi farvi riferimento in modo appropriato nell'articolo. Le immagini verranno visualizzate automaticamente a dimensioni intere, il che significa che le immagini di grandi dimensioni riempiranno l'intera larghezza dell'articolo. È consigliabile pre-ridimensionare le immagini prima di caricarle. La larghezza consigliata è compresa tra 600 e 700 pixel, anche se è consigliabile ridimensionare rispettivamente se si tratta di uno screenshot denso o di una frazione di uno screenshot.

Importante

È possibile caricare immagini solo nel repository copiato tramite fork prima dell'unione. Pertanto, se si prevede di aggiungere immagini a un articolo, è necessario usare Visual Studio Code per aggiungere le immagini alla cartella "images" del fork o assicurarsi di aver eseguito le operazioni seguenti in un Web browser:

  1. Creare una copia tramite fork del repository MicrosoftDocs/hololens.
  2. Modificato l'articolo nel fork.
  3. Caricare le immagini a cui si fa riferimento nell'articolo nella cartella "hololens/images" nel fork.
  4. È stata creata una richiesta pull per unire il fork in MicrosoftDocs/hololens ramo principale.

Per informazioni su come configurare un repository con fork personalizzato, seguire le istruzioni per la creazione di un nuovo articolo.

Anteprima del lavoro

Durante la modifica in GitHub tramite un Web browser, è possibile selezionare la scheda anteprima nella parte superiore della pagina per visualizzare in anteprima il lavoro prima del commit.

Nota

L'anteprima delle modifiche in Microsoft Learn è disponibile solo per i dipendenti Microsoft.

Dipendenti Microsoft: quando i contributi sono stati uniti nel ramo predefinito, principale, è possibile esaminare il contenuto prima che diventi pubblico in </hololens?branch=main>. Trovare l'articolo usando il sommario nella colonna a sinistra.

Modifica nel browser e modifica con un client desktop

La modifica nel browser è il modo più semplice per apportare modifiche rapide, tuttavia esistono alcuni svantaggi:

  • Non si ottiene il controllo ortografico.
  • Non si ottiene alcun collegamento intelligente ad altri articoli (è necessario digitare manualmente il nome del file dell'articolo).
  • Può essere un problema caricare e fare riferimento alle immagini.

Se si preferisce non risolvere questi problemi, usare un client desktop come Visual Studio Code con un paio di estensioni utili quando si contribuisce.

Uso di Visual Studio Code

Per i motivi elencati sopra, è consigliabile usare un client desktop per modificare la documentazione anziché un Web browser. È consigliabile usare Visual Studio Code.

Apparecchio

Seguire questa procedura per configurare Visual Studio Code per l'uso con questo repository:

  1. In un Web browser:
    1. Installare Git per il PC.
    2. Installare Visual Studio Code.
    3. Fork MicrosoftDocs/hololens se non è già stato fatto.
    4. Nel fork selezionare Clonare o scaricare e copiare l'URL.
  2. Creare un clone locale del fork in Visual Studio Code:
    1. Dal menu visualizza selezionare riquadro comandi.
    2. Digitare "Git: Clone".
    3. Incollare l'URL copiato.
    4. Scegliere dove salvare il clone nel PC.
    5. Selezionare Apri repository nella finestra popup.

Modifica della documentazione

Usare il flusso di lavoro seguente per apportare modifiche alla documentazione con Visual Studio Code:

Nota

Tutte le linee guida per la modifica di e la creazione di articoli e le nozioni di base di modifica di Markdown, da sopra si applicano anche quando si usa Visual Studio Code.

  1. Assicurarsi che il fork clonato sia aggiornato con il repository ufficiale.

    1. In un Web browser creare una richiesta pull per sincronizzare le modifiche recenti da altri collaboratori nel ramo predefinito di MicrosoftDocs/hololens, principale, al fork (assicurarsi che la freccia punti alla destinazione corretta).

      Sincronizza modifiche da MicrosoftDocs/hololens al fork.

    2. In Visual Studio Code selezionare il pulsante di sincronizzazione per sincronizzare il fork aggiornato al clone locale.

      Fare clic sull'immagine del pulsante di sincronizzazione.

  2. Creare o modificare articoli nel repository clonato usando Visual Studio Code.

    1. Modificare uno o più articoli (se necessario aggiungere immagini alla cartella "images").

    2. Salvare le modifiche in Explorer.

      scegliere

    3. Eseguire il commit di tutte le modifiche nel controllo del codice sorgente (messaggio di commit di scrittura quando richiesto).

      scegliere

    4. Selezionare il pulsante di sincronizzazione per sincronizzare le modifiche all'origine (fork in GitHub).

      Fare clic sul pulsante di sincronizzazione.

  3. In un Web browser creare una richiesta pull per sincronizzare le nuove modifiche nel fork in MicrosoftDocs/hololens principale (assicurarsi che la freccia punti alla destinazione corretta).

    Creare una richiesta pull dal fork in MicrosoftDocs/hololens.

Estensioni utili

Le estensioni di Visual Studio Code seguenti sono utili per la modifica della documentazione:

  • Docs Markdown Extension for Visual Studio Code - Usare ALT+M per visualizzare un menu delle opzioni di creazione di Microsoft Learn, ad esempio:

    • Cercare e fare riferimento alle immagini caricate.
    • Aggiungere formattazione come elenchi, tabelle e callout come >[!NOTE].
    • Ricerca e riferimento a collegamenti e segnalibri interni (collegamenti a sezioni specifiche all'interno di una pagina).
    • Gli errori di formattazione sono evidenziati (posizionare il puntatore del mouse sull'errore per altre informazioni).
  • correttore ortografico del codice - le parole digitate in modo non corretto verranno sottolineate; Fare clic con il pulsante destro del mouse su una parola con errori di ortografia per modificarla o salvarla nel dizionario.