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!
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 |
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:
- 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 prendere in considerazione l'impostazione del messaggio di posta elettronica pubblico su Non visualizzare l'indirizzo di posta elettronica.
- È consigliabile caricare un'immagine del profilo perché viene visualizzata un'anteprima nelle pagine docs a cui si contribuisce.
- Se si prevede di usare la riga di comando, è consigliabile configurare Git Credential Manager per Windows. In questo modo, non è 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.
Usare il flusso di lavoro seguente per apportare aggiornamenti a un articolo esistente tramite GitHub in un Web browser:
Passare all'articolo da modificare nella cartella "mixed-reality-docs".
Selezionare il pulsante di modifica (icona a forma di matita) in alto a destra, che forkerà automaticamente un ramo eliminabile dal ramo 'master'.
Modificare il contenuto dell'articolo in base alle nozioni di base di Markdown.
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.
Dopo aver completato le modifiche dell'articolo, scorrere verso il basso e selezionare Propone modifica file.
Nella pagina successiva selezionare Crea richiesta pull per unire il ramo creato automaticamente in 'master'.
Ripetere i passaggi precedenti per l'articolo successivo che si vuole modificare.
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 conmixed-reality-docs
e termini con.md
. -
redirect_url
è l'URL pubblico relativo dell'articolo precedente al nuovo articolo. Assicurarsi che questo URL non contengamixed-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
. Usaretrue
se si vuole mantenere il valore dell'attributoms.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.
Usare il flusso di lavoro seguente per creare nuovi articoli nel repository della documentazione tramite GitHub in un Web browser:
Creare un fork dal ramo "master" di MicrosoftDocs/realtà mista (usando il pulsante Fork in alto a destra).
Nella cartella "mixed-reality-docs" selezionare Crea nuovo file in alto a destra.
Creare un nome di pagina per l'articolo (usare trattini anziché spazi e non usare segni di punteggiatura o apostrofi) e accodare ".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.
Nella parte superiore della nuova pagina aggiungere il blocco di metadati seguente:
--- title: description: author: ms.author: ms.date: ms.topic: article keywords: ---
Compilare i campi dei metadati pertinenti in base alle istruzioni riportate nella sezione precedente.
Scrivere contenuto dell'articolo usando le nozioni di base di Markdown.
Aggiungere una
## See also
sezione nella parte inferiore dell'articolo con collegamenti ad altri articoli pertinenti.Al termine, selezionare Commit new file (Esegui commit nuovo file).
Selezionare Nuova richiesta pull e unire il ramo "master" del fork in MicrosoftDocs/realtà mista "master" (assicurarsi che la freccia punti al modo corretto).
Le risorse seguenti consentono di apprendere come modificare la documentazione usando il linguaggio Markdown:
- Informazioni di base su Markdown
- Poster di riferimento markdown a colpo d'occhio
- Risorse aggiuntive per la scrittura di Markdown per Microsoft Learn
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.
È 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:
- Forked the MicrosoftDocs/mixed-reality repository.Forked the MicrosoftDocs/mixed-reality repository.
- Modificato l'articolo nel fork.
- Caricare le immagini a cui si fa riferimento nell'articolo nella cartella "mixed-reality-docs/images" nel fork.
- 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.
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.
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.
Per i motivi elencati in precedenza, è consigliabile usare un client desktop per modificare la documentazione anziché un Web browser. È consigliabile usare Visual Studio Code.
Seguire questa procedura per configurare Visual Studio Code per usare questo repository:
- In un Web browser:
- Installare Git per il PC.
- Installare Visual Studio Code.
- Fork MicrosoftDocs/mixed-reality se non è già stato fatto.
- Nel fork selezionare Clona o scarica e copia l'URL.
- Creare un clone locale del fork in Visual Studio Code:
- Dal menu Visualizza selezionare Tavolozza comandi.
- Digitare "Git: Clone".
- Incollare l'URL copiato.
- Scegliere dove salvare il clone nel PC.
- Selezionare Apri repository nel popup.
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.
Assicurarsi che il fork clonato sia aggiornato con il repository ufficiale.
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).
In Visual Studio Code selezionare il pulsante di sincronizzazione per sincronizzare il fork aggiornato al clone locale.
Creare o modificare articoli nel repository clonato usando Visual Studio Code.
Modificare uno o più articoli (aggiungere immagini alla cartella "immagini" se necessario).
Salvare le modifiche in Esplora risorse.
Eseguire il commit di tutte le modifiche nel controllo del codice sorgente (scrivere il messaggio di commit quando richiesto).
Selezionare il pulsante di sincronizzazione per sincronizzare le modifiche all'origine (il fork in GitHub).
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).
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.