Contribuire alla documentazione per sviluppatori di Realtà mista

Benvenuti nel repository pubblico per Realtà mista documentazione per sviluppatori. Tutti gli articoli creati o modificati in questo repository saranno visibili al pubblico.

La documentazione Realtà mista è ora ospitata in Microsoft Learn, che usa GitHub-flavored Markdown con le funzionalità markdig. Il contenuto modificato in questo repository viene formattato in pagine stilizzate che vengono visualizzate in /windows/mixed-reality.

Questa pagina descrive i passaggi e le linee guida da seguire per apportare il proprio contributo, oltre ai link per apprendere i fondamenti di Markdown. Grazie per il tuo contributo!

Repository disponibili

Nome del repository	URL
Rendering remoto di Azure	MicrosoftDocs/azure-docs/articles/remote-rendering
HoloLens	MicrosoftDocs/HoloLens
Realtà mista	MicrosoftDocs/realtà mista
Guida per gli appassionati di VR	MicrosoftDocs/mixed-reality/enthusiast-guide

Prima di iniziare

Se non ne hai già uno, dovrai creare un account GitHub.

Nota

Se si è un dipendente Microsoft, collegare l'account GitHub all'alias Microsoft nel portale Microsoft Open Source. Partecipa alle organizzazioni "Microsoft" e "MicrosoftDocs ".

Durante la configurazione del tuo account GitHub, ti consigliamo inoltre di adottare le seguenti precauzioni:

• Creare una password complessa per l'account GitHub.
• Abilitare l'autenticazione a due fattori.
• Salvare i codici di ripristino in un luogo sicuro.
• Aggiornare le impostazioni del profilo pubblico.
  • Impostare il nome e impostare l'indirizzo di posta elettronica pubblico su Non visualizzare l'indirizzo di posta elettronica.
  • Poiché nelle pagine a cui contribuisci verrà mostrata una miniatura della tua immagine profilo, ti consigliamo di caricarne una.
• Se si prevede di usare la riga di comando, è consigliabile configurare Git Credential Manager per Windows. In questo modo, non sarà necessario immettere la password ogni volta che si apporta un contributo.

Il sistema di pubblicazione è collegato a GitHub, quindi è importante seguire questi passaggi. Sarai menzionato come autore o collaboratore di ogni articolo con il tuo alias GitHub.

Modificare 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 "mixed-reality-docs".

2. Selezionare il pulsante di modifica (icona a forma di matita) in alto a destra, che forkrà automaticamente un ramo eliminabile dal ramo 'master'.

   

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

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

   • titolo: Titolo della pagina che appare nella scheda del browser durante la visualizzazione dell’articolo. I titoli delle pagine vengono utilizzati per l'ottimizzazione in ottica SEO e l’indicizzazione. Per questo motivo è importante non modificare il titolo se non strettamente necessario (sebbene sia meno grave farlo prima di pubblicare la documentazione).
   • descrizione: Descrivi brevemente il contenuto dell’articolo, per migliorare l'ottimizzazione SEO e permettere agli utenti di scoprirti.
   • autore: Se sei il proprietario principale della pagina, aggiungi qui il tuo alias GitHub.
   • ms.author: Se sei il proprietario principale della pagina, aggiungi qui il tuo alias Microsoft (non serve inserire @microsoft.com, è sufficiente l’alias).
   • ms.data: Aggiorna la data solo se stai aggiungendo contenuti importanti alla pagina, non in caso di correzioni, come chiarimenti, formattazione, grammatica o ortografia.
   • parole chiave: Le parole chiave contribuiscono alla SEO (ottimizzazione per i motori 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 adatte a tutti gli articoli, poiché quelle 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 in 'master'.

7. Ripeti i passaggi precedenti per modificare qualunque altro articolo.

Rinominare o eliminare un articolo esistente

Se la tua modifica consiste nel rinominare o eliminare un articolo esistente, assicurati di aggiungere un reindirizzamento. In questo modo, chiunque possegga un link all’articolo esistente raggiungerà comunque la pagina giusta. I reindirizzamenti sono gestiti dal file .openpublishing.redirection.json, che si trova nella radice del repository.

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

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
    ...
    ]
}

• Il source_path è il percorso del repository relativo al vecchio articolo che stai rimuovendo. Assicurati che il percorso inizi con mixed-reality-docs e finisca con .md.
• Il redirect_url è l’URL pubblico che reindirizza dal vecchio articolo al nuovo articolo. Assicurati che questo URL non contenga mixed-reality-docs o .md, poiché fa riferimento all’URL pubblico e non al percorso del repository. Il collegamento a una sezione all'interno del nuovo articolo che usa #section è consentito. Se necessario, è anche possibile usare un percorso assoluto per un altro sito.
• redirect_document_id indica se desideri mantenere l’ID del documento del file precedente. Il valore predefinito è false. Usare true se si vuole mantenere il valore dell'attributo ms.documentid dall'articolo reindirizzato. Se conservi l’ID del documento, i dati, come il numero di visualizzazioni e il ranking della pagina, verranno trasferiti all’articolo di destinazione. Esegui questa operazione se lo scopo del reindirizzamento è principalmente quello di rinominare un articolo, non di trasferire l'utente sulla pagina di un articolo diverso e solo in parte correlato al primo.

Se aggiungi un reindirizzamento, assicurati inoltre di avere eliminato il vecchio file.

Creare 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 una fork dal ramo "master" di MicrosoftDocs/realtà mista (usando il pulsante Fork in alto a destra).

   

2. Nella cartella "mixed-reality-docs" selezionare Crea nuovo file in alto a destra.

3. Dai un nome alla pagina dell’articolo (usa i trattini al posto degli spazi e non usare punteggiatura o apostrofi) e aggiungi “.md”

   

   Importante

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

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

   ---
   title:
   description:
   author:
   ms.author:
   ms.date:
   ms.topic: article
   keywords:
   ---
   

5. Compilare i campi dei metadati pertinenti in base alle istruzioni riportate nella sezione precedente.

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

7. Aggiungi una sezione ## See also in fondo all’articolo con link ad altri articoli pertinenti.

8. Al termine, selezionare Commit nuovo file.

9. Selezionare Nuova richiesta pull e unire il ramo 'master' del fork in MicrosoftDocs/realtà mista 'master' (assicurarsi che la freccia punti al modo corretto).

   

Fondamenti di Markdown

Con le seguenti risorse potrai imparare a modificare la documentazione utilizzando il linguaggio Markdown:

• Fondamenti di Markdown
• Poster di riferimento Markdown a colpo d’occhio
• Risorse aggiuntive per la scrittura di Markdown per Microsoft Learn

Aggiungere tabelle

A causa del modo in cui le tabelle della documentazione tecnica Microsoft non hanno bordi o stili personalizzati, anche se si prova css inline. Lo stile sembrerà funzionare per un breve periodo di tempo, ma alla fine la piattaforma lo eliminerà dalla tabella. Fai tesoro di questa informazione e crea tabelle semplici. Ecco un sito che semplifica le tabelle Markdown.

L'estensione Docs Markdown per Visual Studio Code semplifica anche la generazione di tabelle se si usa Visual Studio Code (vedere di seguito) per modificare la documentazione.

Aggiungere immagini

Sarà necessario caricare le immagini nella cartella "mixed-reality-docs/images" nel repository e quindi farvi riferimento in modo appropriato nell'articolo. Le immagini verranno visualizzate automaticamente in full-size, di conseguenza l'intera l'articolo si riempirà di immagini molto grandi. Ti consigliamo di 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 nel repository biforcato solo prima dell’unione. Pertanto, se si prevede di aggiungere immagini a un articolo, è necessario usare Visual Studio Code per aggiungere prima le immagini alla cartella "immagini" del fork o assicurarsi di aver eseguito le operazioni seguenti in un Web browser:

1. Creazione di una copia tramite fork del repository MicrosoftDocs/realtà mista.
2. Avere modificato l’articolo nella tua biforcazione.
3. Caricare le immagini a cui si fa riferimento nell'articolo nella cartella "mixed-reality-docs/images" nel fork.
4. È stata creata una richiesta pull per unire il fork nel ramo "master" di MicrosoftDocs/realtà mista.

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

Visualizzare l'anteprima del tuo 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 di eseguire il commit.

Nota

L'anteprima delle modifiche a fasi è disponibile solo per i dipendenti Microsoft

Dipendenti Microsoft: dopo che i contributi sono stati uniti nel ramo 'main', è possibile esaminare il contenuto prima che diventi pubblico in /windows/mixed-reality?branch=main. Puoi trovare il tuo articolo utilizzando l’indice nella colonna di sinistra.

Modifica nel browser e modifica con un client desktop

Il browser è lo strumento più semplice e rapido per apportare modifiche, tuttavia, presenta alcuni svantaggi:

• Non hai a disposizione il controllo ortografico.
• Non hai a disposizione alcun collegamento intelligente ad altri articoli (devi digitare manualmente il nome del file dell’articolo).
• Può essere faticoso caricare le immagini e creare dei riferimenti.

Se si preferisce non gestire questi problemi, usare un client desktop come Visual Studio Code con un paio di estensioni utili per contribuire.

Usare Visual Studio Code

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

Configurazione

Segui questi passaggi per configurare Visual Studio Code in modo da renderlo compatibile con questo repository:

1. In un Web browser:
   1. Installare Git per il PC.
   2. Installare Visual Studio Code.
   3. Creare una copia tramite fork di MicrosoftDocs/realtà mista , se non è già stato fatto.
   4. Nel fork selezionare Clona o scarica e copiare l'URL.
2. Creare un clone locale del fork in Visual Studio Code:
   1. Dal menu Visualizza, selezionare Riquadro comandi.
   2. Digita “Git: Clona”.
   3. Incolla l’URL che hai copiato.
   4. Scegli dove salvare il clone sul tuo PC.
   5. Selezionare Apri repository nel popup.

Modificare la documentazione

Segui i passaggi qui riportati per apportare modifiche alla documentazione con Visual Studio Code:

Nota

Tutte le linee guida per la modifica e la creazione di articoli e le nozioni di base sulla modifica di Markdown sono valide anche quando si usa Visual Studio Code.

1. Assicurati che la biforcazione clonata sia sincronizzata con il repository ufficiale.

   1. In un Web browser creare una richiesta pull per sincronizzare le modifiche recenti da altri collaboratori in MicrosoftDocs/realtà mista 'master' al fork (assicurarsi che la freccia punti al modo giusto).

      

   2. In Visual Studio Code, seleziona il pulsante di sincronizzazione per sincronizzare la biforcazione appena aggiornata con il clone locale.

      

2. Crea o modifica articoli nel repository clonato utilizzando Visual Studio Code.

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

   2. Salva modifiche in Explorer.

      

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

      

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

      

3. In un Web browser creare una richiesta pull per sincronizzare le nuove modifiche nel fork in MicrosoftDocs/realtà mista 'master' (assicurarsi che la freccia punti al modo corretto).

   

Estensioni utili

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

• Docs Markdown Extension for Visual Studio Code - Use ALT+M to bring up a menu of docs authoring options like:Docs Markdown Extension for Visual Studio Code - Use ALT+M to bring up a menu of docs authoring options like:
  • Cercare e fare riferimento alle immagini caricate.
  • Aggiungere formattazione come elenchi, tabelle e callout specifici della documentazione, ad esempio >[!NOTE].
  • Cercare e fare riferimento a link interni e segnalibri (link a sezioni specifiche all’interno di una pagina).
  • Formattare errori evidenziati (passa il mouse sull’errore per scoprire di più).
• Correttore ortografico del codice: le parole con errori di ortografia verranno sottolineate; fare clic con il pulsante destro del mouse su una parola con errori di ortografia per modificarla o salvarla nel dizionario.