Contribution à la documentation des développeurs Mixed Reality

Bienvenue dans le référentiel public pour Mixed Reality documentation des développeurs ! Tous les articles que vous créerez ou modifierez dans ce référentiel seront publics.

Les documents Mixed Reality sont désormais hébergés sur Microsoft Learn, qui utilise Markdown avec saveur GitHub avec les fonctionnalités Markdig. Le contenu que vous modifiez dans ce référentiel est mis en forme dans des pages stylisées qui s’affichent à /windows/mixed-reality.

Cette page décrit les étapes et les instructions de base de la contribution et contient des liens vers les bases de Markdown. Merci beaucoup pour votre contribution.

Référentiels disponibles

Nom du dépôt	URL
Azure Object Anchors	MicrosoftDocs/azure-docs/articles/object-anchors
Azure Remote Rendering	MicrosoftDocs/azure-docs/articles/remote-rendering
Azure Spatial Anchors	MicrosoftDocs/azure-docs/articles/spatial-anchors
HoloLens	MicrosoftDocs/HoloLens
Mixed Reality	MicrosoftDocs/mixed-reality
Guide à l'attention des passionnés de réalité virtuelle	MicrosoftDocs/mixed-reality/enthusiast-guide

Avant de commencer

Si ce n'est déjà fait, vous devez créer un compte GitHub.

Notes

Si vous êtes un employé de Microsoft, liez votre compte GitHub à votre alias Microsoft sur le portail open source de Microsoft. Rejoignez les organisations « Microsoft » et « MicrosoftDocs ».

Lors de la configuration de votre compte GitHub, nous vous recommandons également de prendre les précautions suivantes en matière de sécurité :

• Créez un mot de passe fort pour votre compte Github.
• Activez l'authentification à 2 facteurs.
• Conservez vos codes de récupération dans un endroit sûr.
• Mettez à jour les paramètres de votre profil public.
  • Définissez votre nom, et pensez à définir votre e-mail public sur Ne pas afficher mon adresse e-mail.
  • Nous vous recommandons de charger un avatar, car une miniature apparaît sur les pages des documents auxquels vous contribuez.
• Si vous prévoyez d'utiliser la ligne de commande, pensez à configurer le Gestionnaire d'informations d'identification Git pour Windows. Ainsi, vous n’aurez pas à entrer votre mot de passe chaque fois que vous effectuerez une contribution.

Dans la mesure où le système de publication est lié à GitHub, ces étapes sont importantes. Vous serez répertorié en tant qu'auteur ou contributeur de chaque article en utilisant votre alias GitHub.

Modifier un article existant

Utilisez le flux de travail suivant pour mettre à jour un article existant via GitHub dans un navigateur web :

1. Accédez à l’article que vous souhaitez modifier dans le dossier « mixed-reality-docs ».

2. Sélectionnez le bouton d’édition (icône de crayon) en haut à droite, qui biche automatiquement une branche jetable de la branche « maître ».

   

3. Modifiez le contenu de l’article en fonction des principes de base de Markdown.

4. Mettez à jour les métadonnées en haut de chaque article :

   • title : titre de la page qui apparaît dans l'onglet du navigateur lorsque l'article est consulté. Le titre de la page est utilisé pour le référencement et l'indexation. Par conséquent, ne le modifiez que si cela s'avère vraiment nécessaire (sachant que cela sera moins problématique si la modification est effectuée avant que la documentation ne soit rendue publique).
   • description : rédigez une brève description du contenu de l'article pour faciliter le référencement et la découverte.
   • author : si vous êtes le propriétaire principal de la page, ajoutez votre alias GitHub ici.
   • ms.author : si vous êtes le propriétaire principal de la page, ajoutez votre alias Microsoft ici (vous n’avez pas besoin @microsoft.comde , juste l’alias).
   • ms.date : mettez la date à jour si vous ajoutez du contenu important à la page, mais pas pour les corrections de types clarification, mise en forme, grammaire ou orthographe.
   • keywords : les mots-clés sont utiles pour le référencement (optimisation des moteurs de recherche). Ajoutez des mots-clés, séparés par une virgule et un espace, qui sont spécifiques à votre article, mais sans ponctuation après le dernier mot-clé de votre liste. Vous n'avez pas besoin d'ajouter des mots-clés globaux qui s'appliquent à tous les articles, car ceux-ci sont gérés ailleurs.

5. Une fois l'article modifié, faites défiler la page et sélectionnez Proposer une modification de fichier.

6. Sur la page suivante, sélectionnez Créer une demande de tirage pour fusionner votre branche créée automatiquement dans « master ».

7. Répétez les étapes ci-dessus pour le prochain article que vous souhaitez modifier.

Renommer ou supprimer un article existant

Si votre modification a pour effet de renommer ou de supprimer un article existant, veillez à ajouter une redirection. Ainsi, toute personne disposant d’un lien vers l’article existant se retrouvera toujours au bon endroit. Les redirections sont gérées par le fichier .openpublishing.redirection.json à la racine du référentiel.

Pour ajouter une redirection au fichier .openpublishing.redirection.json, ajoutez une entrée au tableau redirections :

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

• source_path est le chemin relatif du référentiel vers l'ancien article que vous supprimez. Vérifiez que le chemin commence par mixed-reality-docs et se termine par .md.
• redirect_url est l'URL publique relative de l'ancien article vers le nouveau. Assurez-vous que cette URL ne contient mixed-reality-docs pas ou .md, car elle fait référence à l’URL publique et non au chemin du dépôt. La création d'un lien vers une section du nouvel article à l'aide de #section est autorisée. Vous pouvez également utiliser un chemin absolu vers un autre site, si nécessaire.
• redirect_document_id indique si vous souhaitez conserver l'ID de document du fichier précédent. Par défaut, il s’agit de false. Utilisez true si vous souhaitez conserver la valeur de l’attribut ms.documentid de l’article redirigé. Si vous conservez l’ID du document, les données, comme les consultations de la page et les classements, sont transférées vers l’article cible. Procédez ainsi si la redirection est principalement un changement de nom, et non un pointeur vers un autre article qui ne couvre qu’une partie du même contenu.

Si vous ajoutez une redirection, veillez également à supprimer l’ancien fichier.

Créer un article

Utilisez le flux de travail suivant pour créer des articles dans le référentiel de documentation via GitHub dans un navigateur web :

1. Créez une duplication sur la branche « master » MicrosoftDocs/mixed-reality (à l’aide du bouton Duplication en haut à droite).

   

2. Dans le dossier « mixed-reality-docs », sélectionnez Créer un fichier en haut à droite.

3. Créez un nom de page pour l'article (utilisez des traits d'union plutôt que des espaces, et n'utilisez pas de signes de ponctuation ou d'apostrophes) et ajoutez « .md ».

   

   Important

   Veillez à créer le nouvel article à partir du dossier « mixed-reality-docs ». Vous pouvez confirmer cela en vérifiant la valeur « /mixed-reality-docs/ » dans la nouvelle ligne de nom de fichier.

4. En haut de votre nouvelle page, ajoutez le bloc de métadonnées suivant :

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

5. Renseignez les champs de métadonnées appropriés conformément aux instructions de la section ci-dessus.

6. Écrivez du contenu d’article en utilisant les principes de base de Markdown.

7. Ajoutez une section ## See also en bas de l’article avec des liens vers d’autres articles pertinents.

8. Lorsque vous avez terminé, sélectionnez Valider le nouveau fichier.

9. Sélectionnez Nouvelle demande de tirage et fusionnez la branche « maître » de votre fourche dans MicrosoftDocs/mixed-reality « master » (vérifiez que la flèche pointe dans le bon sens).

   

Les bases de Markdown

Les ressources suivantes vous permettront d'apprendre à modifier de la documentation à l'aide du langage Markdown :

• Principes de base de Markdown
• Affiche de référence Markdown-at-a-glance
• Ressources supplémentaires pour l’écriture de Markdown pour Microsoft Learn

Ajouter des tableaux

En raison de la façon dont les tables de la documentation technique Microsoft s’affichent, elles n’auront pas de bordures ou de styles personnalisés, même si vous essayez css inline. Cela semblera fonctionner brièvement, mais la plateforme finira par supprimer le style du tableau. Vous devez donc anticiper et veiller à ce que vos tableaux restent simples. Voici un site qui facilite les tables Markdown.

Docs Markdown Extension for Visual Studio Code facilite également la génération de tableaux si vous utilisez Visual Studio Code (voir ci-dessous) pour modifier la documentation.

Ajout d’images

Vous devez charger vos images dans le dossier « mixed-reality-docs/images » dans le référentiel, puis les référencer de manière appropriée dans l’article. Les images apparaîtront automatiquement en taille réelle, ce qui signifie que les grandes images occuperont toute la largeur de l'article. Nous vous recommandons de prédimensionner vos images avant de les charger. La largeur recommandée est comprise entre 600 et 700 pixels, mais vous devez augmenter ou réduire la taille s'il s'agit d'une capture d'écran dense ou d'une fraction d'une capture d'écran, respectivement.

Important

Vous pouvez uniquement charger des images sur vos référentiels dupliqués avant la fusion. Ainsi, si vous prévoyez d'ajouter des images à un article, vous devez d'abord utiliser Visual Studio Code pour ajouter les images au dossier « images » de votre duplication ou vous assurer que vous avez effectué les opérations suivantes dans un navigateur web :

1. Fork le référentiel MicrosoftDocs/mixed-reality.
2. Modification de l’article dans votre duplication
3. Chargez les images que vous référencez dans votre article dans le dossier « mixed-reality-docs/images » de votre duplication.
4. Création d’une demande de tirage pour fusionner votre duplication dans la branche « maître » MicrosoftDocs/mixed-reality.

Pour apprendre à configurer votre propre référentiel dupliqué, suivez les instructions disponibles dans Créer un article.

Aperçu de votre travail

Lorsque vous apportez des modifications dans GitHub via un navigateur web, vous pouvez sélectionner l'onglet Aperçu en haut de la page pour prévisualiser votre travail avant de le valider.

Notes

L’aperçu de vos modifications intermédiaires n’est disponible que pour les employés De Microsoft

Employés Microsoft : une fois que vos contributions ont été fusionnées dans la branche « main », vous pouvez consulter le contenu avant qu’il ne soit public à l’adresse /windows/mixed-reality?branch=main. Recherchez votre article à l’aide de la table des matières dans la colonne de gauche.

Modification dans le navigateur ou modification avec un client de bureau

La modification dans le navigateur est le moyen le plus simple d'apporter des modifications rapides, mais elle présente quelques inconvénients :

• Vous n’avez pas de correcteur orthographique.
• Vous n’obtenez pas de liaison intelligente vers d’autres articles (vous devez taper manuellement le nom de fichier de l’article).
• Le chargement et le référencement des images peuvent s'avérer fastidieux.

Si vous préférez ne pas vous occuper de ces problèmes, utilisez un client de bureau comme Visual Studio Code avec quelquesextensions utiles pour apporter votre contribution.

Utilisation de Visual Studio Code

Pour les raisons mentionnées ci-dessus, vous préférerez peut-être utiliser un client de bureau pour modifier la documentation plutôt qu’un navigateur web. Nous vous recommandons d’utiliser Visual Studio Code.

Programme d’installation

Procédez comme suit pour configurer Visual Studio Code afin qu’il fonctionne avec ce référentiel :

1. Dans un navigateur web :
   1. Installez Git pour votre PC.
   2. Installez Visual Studio Code.
   3. Fork MicrosoftDocs/mixed-reality si vous ne l’avez pas déjà fait.
   4. Dans votre duplication, sélectionnez Cloner ou télécharger et copiez l’URL.
2. Créez un clone local de votre duplication dans Visual Studio Code :
   1. Dans le menu Affichage, sélectionnez Palette de commandes.
   2. Entrez « Git: Clone ».
   3. Collez l’URL que vous avez copiée.
   4. Choisissez l'emplacement d'enregistrement du clone sur votre PC.
   5. Sélectionnez Ouvrir le référentiel dans la fenêtre contextuelle.

Modifier la documentation

Utilisez le flux de travail suivant pour apporter des modifications à la documentation avec Visual Studio Code :

Notes

Toutes les instructions relatives à la modification et à la création d’articles, de même que les bases de la modification Markdown, présentées ci-dessus s’appliquent également à l’utilisation de Visual Studio Code.

1. Assurez-vous que votre duplication clonée est à jour par rapport au référentiel officiel.

   1. Dans un navigateur web, créez une demande de tirage pour synchroniser les modifications récentes d’autres contributeurs dans MicrosoftDocs/mixed-reality « master » avec votre duplication (vérifiez que la flèche pointe vers la droite).

      

   2. Dans Visual Studio Code, sélectionnez le bouton Synchroniser pour synchroniser votre duplication fraîchement mise à jour avec le clone local.

      

2. Créez ou modifiez des articles de votre référentiel cloné à l’aide de Visual Studio Code.

   1. Modifiez un ou plusieurs articles (si nécessaire, ajoutez des images au dossier « images »).

   2. Choisissez d'Enregistrer les modifications dans l'Explorateur.

      

   3. Choisissez Valider tout pour valider toutes les modifications dans Contrôle de code source (écrivez un message de validation lorsque vous y êtes invité).

      

   4. Sélectionnez le bouton Synchroniser pour resynchroniser vos modifications avec l’origine (votre duplication située sur GitHub).

      

3. Dans un navigateur web, créez une demande de tirage pour synchroniser les nouvelles modifications apportées à votre duplication avec MicrosoftDocs/mixed-reality 'master' (vérifiez que la flèche pointe vers le bon sens).

   

Extensions utiles

Les extensions suivantes de Visual Studio Code sont utiles lors des modifications de la documentation :

• Docs Markdown Extension for Visual Studio Code : appuyez sur Alt+M pour afficher un menu d'options de création de documents, par exemple :
  • Rechercher et référencer les images que vous avez chargées
  • Ajouter des mises en forme telles que des listes, des tableaux et des mentions spécifiques aux documents, comme >[!NOTE]
  • Rechercher et référencer les liens internes et les signets (liens vers des sections spécifiques d'une page)
  • Mettre en surbrillance les erreurs de mise en forme (passez la souris sur l'erreur pour en savoir plus)
• Vérificateur orthographique de code : les mots mal orthographiés sont soulignés. Cliquez avec le bouton droit sur un mot mal orthographié pour le modifier ou ou l'enregistrer dans le dictionnaire.