Lire en anglais

Partager via


Contribution à la documentation HoloLens

Bienvenue dans la documentation HoloLens! Tous les articles que vous créez ou modifiez dans ce référentiel seront visibles au public.

La documentation HoloLens est publiée sur Microsoft Learn, qui utilise GitHub-flavored Markdown avec des 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 à /hololens.

Cette page décrit les étapes de base et les instructions relatives à la contribution et aux liens vers les bases de Markdown. Merci pour votre contribution !

Dépôts disponibles

Nom du référentiel URL
HoloLens MicrosoftDocs/HoloLens
Réalité mixte microsoftDocs/mixed-reality
Guide des passionnés de VR MicrosoftDocs/mixed-reality/passionné-guide

Avant de commencer

Si vous n’en avez pas encore, vous devez créer un compte GitHub.

Notes

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

Lors de la configuration de votre compte GitHub, nous vous recommandons également ces précautions de sécurité :

  • Créez un mot de passe fort pour votre compte GitHub.
  • Activez d’authentification à deux facteurs.
  • Enregistrez vos codes de récupération dans un endroit sûr.
  • Mettez à jour vos paramètres de profil public .
    • Définissez votre nom et envisagez de définir votre de messagerie publique sur Ne pas afficher mon adresse e-mail.
    • Nous vous recommandons de charger une image de profil, car une miniature est affichée dans les articles Microsoft Learn auxquels vous contribuez.
  • Si vous envisagez d’utiliser la ligne de commande, envisagez de configurer Gestionnaire d’informations d’identification Git pour Windows. De cette façon, vous n’aurez pas besoin d’entrer votre mot de passe chaque fois que vous apportez une contribution.

Le système de publication est lié à GitHub. Ces étapes sont donc importantes. Vous serez répertorié en tant qu’auteur ou contributeur à chaque article à l’aide de votre alias GitHub.

Modification d’un article existant

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

  1. Accédez à l’article que vous souhaitez modifier dans le dossier « hololens ».

  2. Sélectionnez le bouton Modifier (icône de crayon) en haut à droite.

    Modifier un article.

    Cela va automatiquement fork une branche jetable hors de la branche par défaut, principal .

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

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

    • titre: titre de page qui apparaît dans l’onglet navigateur lorsque l’article est affiché. Les titres de page sont utilisés pour le référencement et l’indexation. Ne modifiez donc pas le titre, sauf si nécessaire (bien que cela soit moins critique avant que la documentation ne soit publique).
    • description: écrivez une brève description du contenu de l’article, ce qui améliore le référencement et la découverte.
    • auteur: si vous êtes le propriétaire principal de la page, ajoutez ici votre alias GitHub.
    • ms.author: si vous êtes le propriétaire principal de la page, ajoutez ici votre alias Microsoft (vous n’avez pas besoin d'@microsoft.com, juste l’alias).
    • ms.date: mettez à jour la date si vous ajoutez du contenu majeur à la page, mais pas pour les correctifs tels que la clarification, la mise en forme, la grammaire ou l’orthographe.
    • mots clés: les mots clés facilitent le référencement (optimisation du moteur de recherche). Ajoutez des mots clés, séparés par une virgule et un espace, spécifiques à votre article, mais aucune ponctuation après le dernier mot clé de votre liste. Vous n’avez pas besoin d’ajouter de mots clés globaux qui s’appliquent à tous les articles, car ceux-ci sont gérés ailleurs.
  5. Une fois que vous avez terminé vos modifications d’article, faites défiler vers le bas et sélectionnez Proposer une modification de fichier.

  6. Dans la page suivante, sélectionnez Créer une demande de tirage pour fusionner votre branche créée automatiquement dans la branche par défaut, principale.

  7. Répétez les étapes ci-dessus pour l’article suivant que vous souhaitez modifier.

Renommage ou suppression d’un article existant

Si votre modification renomme ou supprime un article existant, veillez à ajouter une redirection. De cette façon, 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 vers .openpublishing.redirection.json, ajoutez une entrée au tableau redirections :

{
    "redirections": [
        {
            "source_path": "hololens/old-article",
            "redirect_url": "/base-url/new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • Le source_path est le chemin d’accès relatif du référentiel à l’ancien article que vous supprimez. Vérifiez que le chemin commence par l’ensemble de documents (dans ce cas, hololens) et inclut l’extension de fichier .md.

  • La redirect_url est l’URL publique relative de l’ancien article vers le nouvel article. Assurez-vous que cette URL ne contient pas contenir .md et commence par /, car elle fait référence à l’URL publique et non au chemin du référentiel. La liaison à une section dans le nouvel article à l’aide de #section est autorisée. Vous pouvez également utiliser un chemin absolu vers un autre site ici, si nécessaire.

  • redirect_document_id indique si vous souhaitez conserver l’ID de document du fichier précédent. La valeur par défaut est false. Utilisez true si vous souhaitez conserver la valeur d’attribut ms.documentid de l’article redirigé. Si vous conservez l’ID de document, les données, telles que les affichages de pages et les classements, seront transférées vers l’article cible. Pour ce faire, si la redirection est principalement un renommage, et non un pointeur vers un autre article qui couvre uniquement certains des mêmes contenus.

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

Création d’un article

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

  1. Créez une duplication hors de la branche par défaut, principale, de MicrosoftDocs/hololens à l’aide du bouton Fork en haut à droite.

    branche par défaut, actuellement nommée « main ».

  2. Dans le dossier « hololens », sélectionnez Créer un fichier en haut à droite.

  3. Créez un nom de page pour l’article (utilisez des traits d’union au lieu d’espaces et n’utilisez pas de ponctuation ou d’apostrophes) et ajoutez .md »

    Nommez votre nouvelle page.

    Important

    Veillez à créer le nouvel article à partir du dossier « hololens ». Vous pouvez le confirmer en vérifiant « /hololens/ » 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 pertinents, comme décrit précédemment dans Modification d’un article existant.

  6. Écrivez du contenu d’article à l’aide de 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 principale de votre fourche dans MicrosoftDocs/hololens principal (vérifiez que la flèche pointe vers la destination correcte).

    Créer une demande de tirage à partir de votre fourche dans MicrosoftDocs/hololens.

Notions de base de Markdown

Les ressources suivantes vous aideront à apprendre à modifier la documentation à l’aide de la langue Markdown :

Ajout de tables

En raison de la façon dont les tables sont mises en forme sur Microsoft Learn, elles n’ont pas de bordures ou de styles personnalisés, même si vous essayez css inline. Il semble fonctionner pendant une courte période, mais finalement la plate-forme supprime le style de la table. Planifiez donc vos tables avant et gardez vos tables simples. Voici un site qui facilite les tables Markdown : [Générateur de tables](https://www.tablesgenerator.com/markdown_tables).

L’extension Docs Markdown 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.

Ajout d’images

Vous devez charger vos images dans le dossier « hololens/images » dans le référentiel, puis les référencer correctement dans l’article. Les images s’affichent automatiquement à pleine taille, ce qui signifie que les images volumineuses remplissent toute la largeur de l’article. Nous vous recommandons de redimensionner vos images avant de les charger. La largeur recommandée est comprise entre 600 et 700 pixels, bien que vous deviez dimensionner vers le haut ou le bas 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 dans votre dépôt forked avant de fusionner. Par conséquent, si vous envisagez d’ajouter des images à un article, vous devez utiliser Visual Studio Code pour ajouter d’abord les images au dossier « images » de votre fourche ou vous assurer que vous avez effectué ce qui suit dans un navigateur web :

  1. Forked the MicrosoftDocs/hololens repo.
  2. Modification de l’article dans votre fourche.
  3. Chargez les images que vous référencez dans votre article dans le dossier « hololens/images » dans votre fourche.
  4. Créez une demande de tirage pour fusionner votre duplication dans la branche principale microsoftDocs/hololens.

Pour savoir comment configurer votre propre dépôt forked, suivez les instructions pour la création d’un nouvel article.

Aperçu de votre travail

Lors de la modification dans GitHub via un navigateur web, vous pouvez sélectionner l’onglet Aperçu en haut de la page pour afficher un aperçu de votre travail avant de valider.

Notes

La préversion de vos modifications sur Microsoft Learn n’est disponible que pour les employés de Microsoft.

Employés de Microsoft : lorsque vos contributions ont été fusionnées dans la branche par défaut, principale, vous pouvez passer en revue le contenu avant qu’il ne soit public à </hololens ?branch=main>. Recherchez votre article à l’aide de la table des matières dans la colonne de gauche.

Modification dans le navigateur et modification avec un client de bureau

La modification dans le navigateur est le moyen le plus simple d’apporter des modifications rapides, mais il existe quelques inconvénients :

  • Vous n’obtenez pas de vérification orthographique.
  • Vous n’obtenez aucune liaison intelligente à d’autres articles (vous devez taper manuellement le nom de fichier de l’article).
  • Il peut s’avérer difficile de charger et de référencer des images.

Si vous préférez ne pas résoudre ces problèmes, utilisez un client de bureau comme Visual Studio Code avec un couple extensions utiles lors de la contribution.

Utilisation de Visual Studio Code

Pour les raisons répertoriées ci-dessus, vous pouvez préférer utiliser un client de bureau pour modifier la documentation au lieu d’un navigateur web. Nous vous recommandons d’utiliser Visual Studio Code.

Coup monté

Procédez comme suit pour configurer Visual Studio Code pour qu’il fonctionne avec ce dépôt :

  1. Dans un navigateur web :
    1. Installez Git pour votre pc.
    2. Installez visual Studio Code.
    3. Fork MicrosoftDocs/hololens si vous ne l’avez pas déjà fait.
    4. Dans votre fourche, 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. Tapez « Git : Cloner ».
    3. Collez l’URL que vous avez copiée.
    4. Choisissez où enregistrer le clone sur votre PC.
    5. Sélectionnez Ouvrir le dépôt dans la fenêtre contextuelle.

Modification de la documentation

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

Notes

Toutes les instructions pour modification et la création d’articles et les notions de base de la modification de Markdown, à partir de ci-dessus s’appliquent également lors de l’utilisation de Visual Studio Code.

  1. Assurez-vous que votre fourche cloné est à jour avec le dépôt officiel.

    1. Dans un navigateur web, créez une demande de tirage pour synchroniser les modifications récentes d’autres contributeurs dans la branche par défaut de MicrosoftDocs/hololens, principal, à votre fourche (vérifiez que la flèche pointe vers la destination correcte).

      Synchroniser les modifications de MicrosoftDocs/hololens vers votre fourche.

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

      Cliquez sur l’image du bouton de synchronisation.

  2. Créez ou modifiez des articles dans votre dépôt cloné à l’aide de Visual Studio Code.

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

    2. Enregistrer les modifications de dans'Explorateur .

      Choisir « Enregistrer tout » dans l’Explorateur

    3. Valider toutes les modifications de dans de contrôle de code source (écrire le message de validation lorsque vous y êtes invité).

      choisir « Valider tout » dans le contrôle de code source

    4. Sélectionnez le bouton synchroniser pour synchroniser vos modifications vers l’origine (votre fourche sur GitHub).

      Cliquez sur le bouton de synchronisation.

  3. Dans un navigateur web, créez une demande de tirage pour synchroniser de nouvelles modifications dans votre fourche vers MicrosoftDocs/hololens principal (vérifiez que la flèche pointe vers la destination correcte).

    Créer une demande de tirage à partir de votre fourche dans MicrosoftDocs/hololens.

Extensions utiles

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

  • Extension Markdown docs pour Visual Studio Code - Utilisez Alt+M pour afficher un menu des options de création Microsoft Learn comme suit :

    • Recherchez et référencez des images que vous avez chargées.
    • Ajoutez une mise en forme telle que des listes, des tableaux et des légendes comme >[!NOTE].
    • Rechercher et référencer des liens internes et des signets (liens vers des sections spécifiques dans une page).
    • Les erreurs de mise en forme sont mises en surbrillance (placez votre souris sur l’erreur pour en savoir plus).
  • vérificateur orthographique de code - les mots mal orthographiés seront soulignés ; Cliquez avec le bouton droit sur un mot mal orthographié pour le modifier ou l’enregistrer dans le dictionnaire.