Leggere in inglese

Condividi tramite


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 Markdown con funzionalità Markdig basate su GitHub. Il contenuto modificato in questo repository viene formattato in pagine stilizzate che vengono visualizzate in /windows/mixed-reality.

Questa pagina illustra i passaggi di base e le linee guida per contribuire e collegamenti alle nozioni di base di Markdown. Grazie per il contributo!

Repository disponibili

Nome del repository URL
Ancoraggi di oggetti di Azure MicrosoftDocs/azure-docs/articles/object-anchors
Rendering remoto di Azure MicrosoftDocs/azure-docs/articles/remote-rendering
Ancoraggi nello spazio di Azure MicrosoftDocs/azure-docs/articles/spatial-anchors
HoloLens MicrosoftDocs/HoloLens
Realtà mista MicrosoftDocs/realtà mista
Guida per gli appassionati di realtà virtuale 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 alle organizzazioni "Microsoft" e "MicrosoftDocs".

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

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

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

    Modificare un articolo.

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

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

    • title: 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.
    • author: se si è il proprietario principale della pagina, aggiungere qui l'alias GitHub.
    • 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: aiuto per le parole chiave in SEO (ottimizzazione del motore di ricerca). Aggiungere parole chiave, separate da una virgola e da uno spazio, specifiche per l'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 Propone modifica file.

  6. Nella pagina successiva selezionare Crea richiesta pull per unire il ramo creato automaticamente in 'master'.

  7. Ripetere i passaggi precedenti per l'articolo successivo che si vuole 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 redirections matrice:

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
    ...
    ]
}
  • source_path è il percorso del repository relativo all'articolo precedente che si sta rimuovendo. Assicurarsi che il percorso inizi con mixed-reality-docs e termini con .md.
  • redirect_url è l'URL pubblico relativo dell'articolo precedente al nuovo articolo. Assicurarsi che questo URL non contenga mixed-reality-docs o .md, perché fa riferimento all'URL pubblico e non al percorso del repository. Il collegamento a una sezione all'interno del nuovo articolo con #section è consentito. 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 conserva l'ID documento, i dati, ad esempio le visualizzazioni 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 dal ramo "master" di MicrosoftDocs/realtà mista (usando il pulsante Fork in alto a destra).

    Creazione di un fork.

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

  3. Creare un nome di pagina per l'articolo (usare trattini anziché 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 "mixed-reality-docs". È possibile confermarlo controllando "/mixed-reality-docs/" 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 in base alle istruzioni riportate nella sezione precedente.

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

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

  8. Al termine, selezionare Commit new file (Esegui 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).

    Creare una richiesta pull dal fork in MicrosoftDocs/realtà mista

Nozioni di base su Markdown

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

Aggiunta di tabelle

A causa del modo in cui le tabelle degli stili della documentazione tecnica Microsoft non avranno bordi o stili personalizzati, anche se si prova CSS inline. Sembra che funzioni 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.

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.

Aggiunta di immagini

È 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 con dimensioni complete, 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 è uno screenshot denso o una frazione di uno screenshot, rispettivamente.

Importante

È possibile caricare immagini solo nel repository fork prima dell'unione. Quindi, 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 fatto quanto segue in un Web browser:

  1. Forked the MicrosoftDocs/mixed-reality repository.Forked the MicrosoftDocs/mixed-reality repository.
  2. Modificato l'articolo nel fork.
  3. Caricare le immagini a cui si fa riferimento nell'articolo nella cartella "mixed-reality-docs/images" nel fork.
  4. Creare una richiesta pull per unire il fork nel ramo MicrosoftDocs/mixed-reality 'master'.

Per informazioni su come configurare il repository forked 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 di eseguire il commit.

Nota

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

Dipendenti Microsoft: una volta uniti i contributi nel ramo "main", è possibile esaminare il contenuto prima di passare al pubblico in /windows/mixed-reality?branch=main. Trovare l'articolo usando il sommario nella colonna sinistra.

Modifica nel browser e modifica con un client desktop

La modifica nel browser è il modo più semplice per apportare modifiche rapide, ma ci sono 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 per 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 in precedenza, è consigliabile usare un client desktop per modificare la documentazione anziché un Web browser. È consigliabile usare Visual Studio Code.

Installazione

Seguire questa procedura per configurare Visual Studio Code per usare questo repository:

  1. In un Web browser:
    1. Installare Git per il PC.
    2. Installare Visual Studio Code.
    3. Fork MicrosoftDocs/mixed-reality se non è già stato fatto.
    4. Nel fork selezionare Clona o scarica e copia l'URL.
  2. Creare un clone locale del fork in Visual Studio Code:
    1. Dal menu Visualizza selezionare Tavolozza comandi.
    2. Digitare "Git: Clone".
    3. Incollare l'URL copiato.
    4. Scegliere dove salvare il clone nel PC.
    5. Selezionare Apri repository nel popup.

Documentazione di modifica

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

Nota

Tutte le linee guida per la modifica e lacreazione di articoli e le nozioni di base sulla modifica di Markdown, in precedenza 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 in MicrosoftDocs/mixed-reality 'master' sul fork (assicurarsi che la freccia punti il modo giusto).

      Sincronizzazione delle modifiche da MicrosoftDocs/realtà mista 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 (aggiungere immagini alla cartella "immagini" se necessario).

    2. Salvare le modifiche in Esplora risorse.

      Scegliere

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

      Scegliere

    4. Selezionare il pulsante di sincronizzazione per sincronizzare le modifiche all'origine (il 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 indietro a MicrosoftDocs/mixed-reality 'master' (assicurarsi che la freccia punti il modo corretto).

    Creare una richiesta pull dal fork in MicrosoftDocs/mixed-reality

Estensioni utili

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

  • Docs Markdown Extension for Visual Studio Code - Usare ALT+M per visualizzare un menu di opzioni di creazione di documenti come:
    • 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 collegamenti interni e segnalibri (collegamenti a sezioni specifiche all'interno di una pagina).
    • La formattazione degli errori è evidenziata (passare il mouse sull'errore per altre informazioni).
  • Controllo ortografico del codice : le parole non scritte verranno sottolineate; fare clic con il pulsante destro del mouse su una parola errata per modificarla o salvarla nel dizionario.