Contribution à la documentation du développeur de réalité mixteContributing to Mixed Reality developer documentation

• 01/11/2021
• 9 minutes de lecture
• • m
  • o

Bienvenue dans la documentation publique référentiel pour les développeurs de réalité mixte!Welcome to the public repo for Mixed Reality developer documentation! Tous les articles que vous créez ou modifiez dans ce référentiel seront visibles par le public.Any articles you create or edit in this repo will be visible to the public.

Les documents de réalité mixte se trouvent désormais sur la plateforme docs.microsoft.com, qui utilise la démarque GitHub-Flavor avec les fonctionnalités Markdig.The Mixed Reality docs are now on the docs.microsoft.com platform, which uses GitHub-flavored Markdown with Markdig features. Le contenu que vous modifiez dans ce référentiel est mis en forme dans des pages stylisées qui s’affichent à l’adresse https://docs.microsoft.com/windows/mixed-reality .The content you edit in this repo gets formatted into stylized pages that show up at https://docs.microsoft.com/windows/mixed-reality.

Cette page décrit les étapes et les instructions de base pour contribuer et les liens vers les concepts de base de la marque.This page covers the basic steps and guidelines for contributing and links to Markdown basics. Merci beaucoup pour votre contribution.Thank you for your contribution!

Pensions disponiblesAvailable repos

Avant de commencerBefore you start

Si vous n’en avez pas déjà un, vous devez créer un compte GitHub.If you don't already have one, you'll need to create a GitHub account.

Lors de la configuration de votre compte GitHub, nous vous recommandons également les précautions de sécurité suivantes :When setting up your GitHub account, we also recommend these security precautions:

• Créez un mot de passe fort pour votre compte GitHub.Create a strong password for your Github account.
• Activez l’authentification à deux facteurs.Enable two-factor authentication.
• Enregistrez vos codes de récupération dans un endroit sûr.Save your recovery codes in a safe place.
• Mettez à jour vos paramètres de profil public.Update your public profile settings.
  • Définissez votre nom et envisagez de configurer votre adresse de messagerie publique pour ne pas afficher mon adresse de messagerie.Set your name, and consider setting your Public email to Don't show my email address.
  • Nous vous recommandons de télécharger une image de profil, car une miniature est affichée sur les pages docs auxquelles vous contribuez.We recommend you upload a profile picture because a thumbnail is shown on docs pages you contribute to.
• Si vous envisagez d’utiliser la ligne de commande, vous pouvez configurer git Credential Manager pour Windows.If you plan to use the command line, consider setting up Git Credential Manager for Windows. De cette façon, vous n’aurez pas à entrer votre mot de passe chaque fois que vous effectuerez une contribution.That way, you won't have to enter your password every time you make a contribution.

Le système de publication est lié à GitHub. ces étapes sont donc importantes.The publishing system is tied to GitHub, so these steps are important. Vous êtes alors inscrit comme auteur ou collaborateur pour chaque article à l’aide de votre alias GitHub.You'll be listed as either author or contributor to each article using your GitHub alias.

Modification d’un article existantEditing an existing article

Utilisez le flux de travail suivant pour effectuer des mises à jour d' un article existant via github dans un navigateur Web :Use the following workflow to make updates to an existing article via GitHub in a web browser:

1. Accédez à l’article que vous souhaitez modifier dans le dossier « Mixed-Real-docs ».Navigate to the article you wish to edit in the "mixed-reality-docs" folder.

2. Sélectionnez le bouton modifier (icône en forme de crayon) dans le coin supérieur droit, qui dupliquera automatiquement une branche jetable en dehors de la branche « master ».Select the edit button (pencil icon) in the top right, which will automatically fork a disposable branch off the 'master' branch.

   

3. Modifiez le contenu de l’article en fonction des « principes de base ».Edit the content of the article according to the "Markdown basics".

4. Mettez à jour les métadonnées en haut de chaque article :Update metadata at the top of each article:

   • titre: titre de la page qui s’affiche sous l’onglet navigateur lorsque l’article est affiché.title: Page title that appears in the browser tab when the article is being viewed. Les titres de page sont utilisés pour le SEO et l’indexation. par conséquent, ne modifiez pas le titre, sauf si cela est nécessaire (bien que cela soit moins critique avant que la documentation ne soit publique).Page titles are used for SEO and indexing, so don't change the title unless necessary (though this is less critical before documentation goes public).
   • Description: rédigez une brève description du contenu de l’article, qui améliore le SEO et la découverte.description: Write a brief description of the article's content, which boosts SEO and discovery.
   • auteur: Si vous êtes le propriétaire principal de la page, ajoutez votre alias GitHub ici.author: If you're the primary owner of the page, add your GitHub alias here.
   • ms. Author: Si vous êtes le propriétaire principal de la page, ajoutez votre alias Microsoft ici (vous n’en avez pas besoin @microsoft.com , juste l’alias).ms.author: If you're the primary owner of the page, add your Microsoft alias here (you don't need @microsoft.com, just the alias).
   • ms. date: mettez à jour la date si vous ajoutez du contenu majeur à la page, mais pas pour des correctifs tels que la clarification, la mise en forme, la grammaire ou l’orthographe.ms.date: Update the date if you're adding major content to the page, but not for fixes like clarification, formatting, grammar, or spelling.
   • Mots clés: aide sur les mots clés dans SEO (optimisation du moteur de recherche).keywords: Keywords aid in SEO (search engine optimization). Ajoutez des mots clés, séparés par une virgule et un espace, qui sont spécifiques à votre article, mais pas de ponctuation après le dernier mot clé de votre liste.Add keywords, separated by a comma and a space, that are specific to your article, but no punctuation after the last keyword in your list. 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.You don't need to add global keywords that apply to all articles, as those are managed elsewhere.

5. Lorsque vous avez terminé les modifications de votre article, faites défiler la liste vers le dessous et sélectionnez proposer une modification de fichier.When you've completed your article edits, scroll down and select Propose file change.

6. Sur la page suivante, sélectionnez créer une demande de tirage (pull Request ) pour fusionner votre branche créée automatiquement dans « Master ».On the next page, select Create pull request to merge your automatically created branch into 'master.'

7. Répétez les étapes ci-dessus pour le prochain article que vous souhaitez modifier.Repeat the steps above for the next article you want to edit.

Attribution d’un nouveau nom ou suppression d’un article existantRenaming or deleting an existing article

Si votre modification renomme ou supprime un article existant, veillez à ajouter une redirection.If your change will rename or delete an existing article, be sure to add a redirect. De cette façon, toute personne disposant d’un lien vers l’article existant continuera de se retrouver au bon endroit.That way, anyone with a link to the existing article will still end up in the right place. Les redirections sont gérées par l' .openpublishing.redirection.jssur le fichier à la racine du référentiel.Redirects are managed by the .openpublishing.redirection.json file in the root of the repo.

Pour ajouter une redirection à .openpublishing.redirection.jssur, ajoutez une entrée au redirections tableau :To add a redirect to .openpublishing.redirection.json, add an entry to the redirections array:

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

• source_pathEst le chemin d’accès relatif au référentiel relatif à l’ancien article que vous supprimez.The source_path is the relative repository path to the old article that you're removing. Assurez-vous que le chemin commence par mixed-reality-docs et se termine par .md .Be sure the path starts with mixed-reality-docs and ends with .md.
• redirect_urlEst l’URL publique relative de l’ancien article vers le nouvel article.The redirect_url is the relative public URL from the old article to the new article. Assurez-vous que cette URL ne contient mixed-reality-docs .md pas ou, car elle fait référence à l’URL publique et non au chemin d’accès au référentiel.Be sure that this URL doesn't contain mixed-reality-docs or .md, as it refers to the public URL and not the repository path. La liaison à une section dans le nouvel article à l’aide de #section est autorisée.Linking to a section within the new article using #section is allowed. Vous pouvez également utiliser un chemin d’accès absolu à un autre site, si nécessaire.You can also use an absolute path to another site here, if necessary.
• redirect_document_id indique si vous souhaitez conserver l’ID du document dans le fichier précédent.redirect_document_id indicates whether you would like to keep the document ID from the previous file. La valeur par défaut est false.The default is false. Utilisez true si vous souhaitez conserver la ms.documentid valeur d’attribut de l’article Redirigé.Use true if you want to preserve the ms.documentid attribute value from the redirected article. Si vous conservez l’ID de document, les données, telles que les affichages de page et les classements, seront transférées vers l’article cible.If you preserve the document ID, data, such as page views and rankings, will be transferred to the target article. Procédez ainsi si la redirection est principalement un changement de nom, et non un pointeur vers un autre article qui couvre uniquement une partie du même contenu.Do this if the redirect is primarily a rename, and not a pointer to different article that only covers some of the same content.

Si vous ajoutez une redirection, veillez à supprimer également l’ancien fichier.If you add a redirect, be sure to delete the old file as well.

Création d’un articleCreating a new article

Utilisez le flux de travail suivant pour créer de nouveaux articles dans la documentation référentiel via github dans un navigateur Web :Use the following workflow to create new articles in the documentation repo via GitHub in a web browser:

1. Créez une fourche à partir de la branche « master » MicrosoftDocs/de la réalité mixte (à l’aide du bouton de branchement dans le coin supérieur droit).Create a fork off the MicrosoftDocs/mixed-reality 'master' branch (using the Fork button in the top right).

   

2. Dans le dossier « Mixed-Real-docs », sélectionnez créer un fichier dans le coin supérieur droit.In the "mixed-reality-docs" folder, select Create new file in the top right.

3. Créer un nom de page pour l’article (utilisez des traits d’Union à la place d’espaces et n’utilisez pas de ponctuation ou d’apostrophes) et ajoutez « . MD »Create a page name for the article (use hyphens instead of spaces and don't use punctuation or apostrophes) and append ".md"

   

   Important

   Veillez à créer le nouvel article dans le dossier « Mixed-Real-docs ».Make sure you create the new article from within the "mixed-reality-docs" folder. Vous pouvez le vérifier en recherchant « /Mixed-Reality-docs/ » dans la ligne du nouveau nom de fichier.You can confirm this by checking for "/mixed-reality-docs/" in the new file name line.

4. En haut de votre nouvelle page, ajoutez le bloc de métadonnées suivant :At the top of your new page, add the following metadata block:

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

5. Renseignez les champs de métadonnées pertinents conformément aux instructions de la section ci-dessus.Fill in the relevant metadata fields per the instructions in the section above.

6. Écrivez le contenu de l’article à l’aide des principes fondamentaux.Write article content using Markdown basics.

7. Ajoutez une ## See also section au bas de l’article avec des liens vers d’autres articles pertinents.Add a ## See also section at the bottom of the article with links to other relevant articles.

8. Lorsque vous avez terminé, sélectionnez valider le nouveau fichier.When finished, select Commit new file.

9. Sélectionnez nouvelle demande de tirage (pull Request ) et fusionnez la branche principale de votre branche dans MicrosoftDocs/Mixed-Reality’Master' (Assurez-vous que la flèche pointe vers la bonne voie).Select New pull request and merge your fork's 'master' branch into MicrosoftDocs/mixed-reality 'master' (make sure the arrow is pointing the correct way).

   

Les bases de MarkdownMarkdown basics

Les ressources suivantes vous permettront d’apprendre à modifier la documentation à l’aide du langage de démarque :The following resources will help you learn how to edit documentation using the Markdown language:

• Principes de base de MarkdownMarkdown basics
• Affiche de référence de démarque-en un clin d’œilMarkdown-at-a-glance reference poster
• Ressources supplémentaires pour l’écriture de la démarque pour docs.microsoft.comAdditional resources for writing Markdown for docs.microsoft.com

Ajout de tablesAdding tables

En raison de la façon dont les tableaux de styles docs.microsoft.com, ils n’ont pas de bordures ou de styles personnalisés, même si vous essayez le style CSS en ligne.Because of the way docs.microsoft.com styles tables, they won’t have borders or custom styles, even if you try inline CSS. Il semblera fonctionner pendant une période de temps limitée, mais la plateforme finira par supprimer le style de la table.It will appear to work for a short period of time, but eventually the platform will strip the styling out of the table. Vous devez donc anticiper et garder vos tables simples.So plan ahead and keep your tables simple. Voici un site qui simplifie les tableaux de démarques.Here’s a site that makes Markdown tables easy.

L' extension docs de démarque pour Visual Studio code facilite également la génération de table si vous utilisez Visual Studio code (voir ci-dessous) pour modifier la documentation.The Docs Markdown Extension for Visual Studio Code also makes table generation easy if you're using Visual Studio Code (see below) to edit the documentation.

Ajouter des imagesAdding images

Vous devez charger vos images dans le dossier « Mixed-Real-docs/images » dans référentiel, puis les référencer de manière appropriée dans l’article.You’ll need to upload your images to the "mixed-reality-docs/images" folder in the repo, and then reference them appropriately in the article. Les images s’affichent automatiquement à la taille maximale, ce qui signifie que les images volumineuses remplissent toute la largeur de l’article.Images will automatically show up at full-size, which means large images will fill the entire width of the article. Nous vous recommandons de prédimensionner vos images avant de les charger.We recommend pre-sizing your images before uploading them. La largeur recommandée est comprise entre 600 et 700 pixels, même si vous devez monter ou diminuer la taille s’il s’agit d’une capture d’écran dense ou d’une fraction d’une capture d’écran, respectivement.The recommended width is between 600 and 700 pixels, though you should size up or down if it’s a dense screenshot or a fraction of a screenshot, respectively.

Aperçu de votre travailPreviewing your work

Pendant la modification dans GitHub via un navigateur Web, vous pouvez sélectionner l’onglet d' Aperçu près du haut de la page pour afficher un aperçu de votre travail avant de le valider.While editing in GitHub via a web browser, you can select the Preview tab near the top of the page to preview your work before committing.

Employés de Microsoft : une fois vos contributions fusionnées dans la branche principale, vous pouvez passer en revue le contenu avant qu’il ne soit public à l’adresse https://review.docs.microsoft.com/windows/mixed-reality?branch=master .Microsoft employees: once your contributions have been merged into the 'master' branch, you can review the content before it goes public at https://review.docs.microsoft.com/windows/mixed-reality?branch=master. Recherchez votre article à l’aide de la table des matières de la colonne de gauche.Find your article using the table of contents in the left column.

Modification dans le navigateur et modification avec un client DesktopEditing in the browser vs. editing with a desktop client

La modification dans le navigateur est le moyen le plus simple pour apporter des modifications rapides, toutefois, il existe quelques inconvénients :Editing in the browser is the easiest way to make quick changes, however, there are a few disadvantages:

• Vous n’avez pas de vérification orthographique.You don't get spell-check.
• Vous n’avez pas de lien intelligent vers d’autres articles (vous devez taper manuellement le nom de fichier de l’article).You don't get any smart-linking to other articles (you have to manually type the article's filename).
• Il peut être laborieux de charger et de référencer des images.It can be a hassle to upload and reference images.

Si vous préférez ne pas traiter ces problèmes, utilisez un client de bureau comme Visual Studio code avec quelques Extensions utiles pour contribuer.If you'd rather not deal with these issues, use a desktop client like Visual Studio Code with a couple helpful extensions when contributing.

Utilisation de Visual Studio CodeUsing 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 au lieu d’un navigateur Web.For the reasons listed above, you may prefer using a desktop client to edit documentation instead of a web browser. Nous vous recommandons d’utiliser Visual Studio code.We recommend using Visual Studio Code.

Programme d’installationSetup

Procédez comme suit pour configurer Visual Studio Code pour qu’il fonctionne avec ce référentiel :Follow these steps to configure Visual Studio Code to work with this repo:

1. Dans un navigateur Web :In a web browser:
   1. Installez git pour votre PC.Install Git for your PC.
   2. Installez Visual Studio Code.Install Visual Studio Code.
   3. Duplication de MicrosoftDocs/Mixed-realisation si vous ne l’avez pas déjà fait.Fork MicrosoftDocs/mixed-reality if you haven't already.
   4. Dans votre fourche, sélectionnez cloner ou télécharger et copiez l’URL.In your fork, select Clone or download and copy the URL.
2. Créez un clone local de votre fourche dans Visual Studio Code :Create a local clone of your fork in Visual Studio Code:
   1. Dans le menu affichage , sélectionnez palette de commandes.From the View menu, select Command Palette.
   2. Tapez « git : Clone ».Type "Git: Clone."
   3. Collez l’URL que vous avez copiée.Paste the URL you copied.
   4. Choisissez l’emplacement où enregistrer le clone sur votre PC.Choose where to save the clone on your PC.
   5. Sélectionnez ouvrir référentiel dans la fenêtre contextuelle.Select Open repo in the pop-up.

Modification de la documentationEditing documentation

Utilisez le flux de travail suivant pour apporter des modifications à la documentation avec Visual Studio Code :Use the following workflow to make changes to the documentation with Visual Studio Code:

1. Assurez-vous que votre fourche cloné est à jour avec la référentiel officielle.Make sure your cloned fork is up to date with the official repo.

   1. Dans un navigateur Web, créez une requête de tirage pour synchroniser les modifications récentes des autres contributeurs de MicrosoftDocs/Mixed-Reality’Master’sur votre fourche (Assurez-vous que la flèche pointe vers la bonne voie).In a web browser, create a pull request to sync recent changes from other contributors in MicrosoftDocs/mixed-reality 'master' to your fork (make sure the arrow is pointing the right way).

      

   2. Dans Visual Studio Code, sélectionnez le bouton synchroniser pour synchroniser votre branche fraîchement mise à jour sur le clone local.In Visual Studio Code, select the sync button to sync your freshly updated fork to the local clone.

      

2. Créez ou modifiez des articles dans votre référentiel cloné à l’aide de Visual Studio Code.Create or edit articles in your cloned repo using Visual Studio Code.

   1. Modifiez un ou plusieurs articles (ajoutez des images au dossier « images » si nécessaire).Edit one or more articles (add images to “images” folder if necessary).

   2. Enregistrer les modifications dans l' Explorateur.Save changes in Explorer.

      

   3. Valide toutes les modifications dans le contrôle de code source (message de validation en écriture quand vous y êtes invité).Commit all changes in Source Control (write commit message when prompted).

      

   4. Sélectionnez le bouton synchroniser pour resynchroniser vos modifications avec l’origine (votre fourche sur GitHub).Select the sync button to sync your changes back to origin (your fork on GitHub).

      

3. Dans un navigateur Web, créez une requête de tirage pour synchroniser les modifications apportées à votre fourche en MicrosoftDocs/Mixed-Reality’Master' (Assurez-vous que la flèche pointe vers la bonne voie).In a web browser, create a pull request to sync new changes in your fork back to MicrosoftDocs/mixed-reality 'master' (make sure the arrow is pointing the correct way).

   

Extensions utilesUseful extensions

Les extensions de Visual Studio Code suivantes sont utiles lors de la modification de la documentation :The following Visual Studio Code extensions are useful when editing documentation:

• Extension docs de la marque pour Visual Studio code -utilisez ALT + M pour afficher un menu d’options de création de documents, comme :Docs Markdown Extension for Visual Studio Code - Use Alt+M to bring up a menu of docs authoring options like:
  • Recherchez et référencez des images que vous avez téléchargées.Search and reference images you've uploaded.
  • Ajoutez une mise en forme comme des listes, des tables et des appels spécifiques aux documents, comme >[!NOTE] .Add formatting like lists, tables, and docs-specific call-outs like >[!NOTE].
  • Recherchez et référencez des liens et des signets internes (liens vers des sections spécifiques dans une page).Search and reference internal links and bookmarks (links to specific sections within a page).
  • Les erreurs de mise en forme sont mises en surbrillance (pointez votre souris sur l’erreur pour en savoir plus).Formatting errors are highlighted (hover your mouse over the error to learn more).
• 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 enregistrez-le dans le dictionnaire.Code Spell Checker - misspelled words will be underlined; right-click on a misspelled word to change it or save it to the dictionary.