Contribuer à la documentation Minecraft Bedrock

2022-04-26

Bienvenue dans le référentiel public de la documentation Minecraft Bedrock. Tous les articles que vous créez ou modifiez dans ce référentiel seront visibles par le public.

Les documents Minecraft Bedrock se trouvent sur la plateforme docs.microsoft.com, qui utilise GitHub Flavored Markdown avec des fonctionnalités Markdig. Le contenu que vous modifiez dans ce référentiel sera formaté dans des pages stylisées Microsoft Docs qui s’affichent dans la Documentation Minecraft Bedrock. Le contenu créé par vous et d’autres membres de la Communauté Bedrock sera publié dans le cadre de nos mises à jour du contenu et de Minecraft: Bedrock Edition.

Cette page couvre les étapes de base et les directives pour contribuer, ainsi que des liens vers les bases de Markdown. Nous vous remercions de votre contribution!

Référentiels disponibles

Nom du référentiel	URL
Minecraft Bedrock docs	https://github.com/MicrosoftDocs/minecraft-creator

Avant de commencer

Si vous n’en avez pas déjà un, vous devrez créer un compte GitHub.

Lors de la création de votre compte GitHub, nous vous recommandons également de prendre les mesures de sécurité suivantes:

Créez un mot de passe fort pour votre compte Github.
Activez l’authentification à deux facteurs.
Conservez vos codes de récupération dans un endroit sûr.
Mettez à jour les paramètres de votre profil public.
- Choisissez votre nom, et pensez à définir votre e-mail public sur Ne pas afficher mon adresse e-mail.
- Nous vous recommandons de télécharger une photo de profil, car une vignette est affichée sur les pages de la documentation auxquelles vous contribuez.
Si vous prévoyez d’utiliser la ligne de commande, pensez à configurer Git Credential Manager pour Windows. De cette façon, vous n’aurez pas à saisir votre mot de passe à chaque fois que vous ferez une contribution.

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

Modifier un article existant

Utilisez le workflow suivant pour mettre à jour un article existant via GitHub dans un navigateur Web:

Accédez à l’article que vous souhaitez modifier dans la documentation des créateurs Minecraft.
Sélectionnez le bouton d’édition (icône en forme de crayon) en haut à droite, qui créera automatiquement une branche jetable de la branche «principale».

Bouton Modifier du portail d’apprentissage

Modifiez le contenu de l’article et le format selon les Notions de base de Markdown.
Mettez à jour les métadonnées en haut de chaque article:
- title: titre de la page qui s’affiche dans l’onglet du navigateur lors de l’affichage de l’article. Les titres de page sont utilisés pour le référencement et l’indexation. Ne modifiez donc le titre que si cela est nécessaire (bien que cela soit moins important avant que la documentation ne soit rendue publique).
- description: rédigez une brève description du contenu de l’article, ce qui favorise 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.auteur: si vous êtes le propriétaire principal de la page, ajoutez votre alias Microsoft ici (vous n’avez pas besoin de @microsoft.com, juste de l’alias).
- ms.date: mettez à jour la date si vous ajoutez du contenu important à la page, mais pas pour des corrections concernant par exemple des clarifications, la mise en forme, la grammaire ou l’orthographe.
- keywords: les mots-clés facilitent le référencement ou encore l’optimisation pour les moteurs de recherche (SEO). 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. 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.
Lorsque vous avez terminé les modifications de votre article, faites défiler la page et sélectionnez Proposer un changement de fichier.
Sur la page suivante, sélectionnez Créer une demande de tirage pour fusionner votre branche créée automatiquement dans le référentiel «principal».
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 ayant 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": "minecraft-creator/creator/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },

La variable source_path correspond au chemin d’accès relatif du référentiel vers l’ancien article que vous supprimez. Assurez-vous que le chemin commence par minecraft-creator/creator et se termine par .md.
La variable redirect_url correspond à l’URL publique relative de l’ancien article au nouvel article. Assurez-vous que cette URL ne contient pas minecraft-creator/creator ou .md, car elle fait référence à l’URL publique et non au chemin d’accès du référentiel. Vous pouvez créer un lien vers une section du nouvel article en utilisant #section. Vous pouvez également utiliser un chemin d’accès 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 la valeur 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 pages vues et les classements, seront transférées vers l’article cible. Procédez ainsi si la redirection concerne principalement un changement de nom, et non un pointeur vers un article différent qui ne couvre qu’une partie du même contenu.

Si vous ajoutez une redirection, assurez-vous de supprimer également l’ancien fichier.

Créer un nouvel article

Utilisez le workflow suivant pour créer de nouveaux articles dans le référentiel de la documentation via GitHub dans un navigateur Web:

Créez un fork à partir de la branche «principale» de MicrosoftDocs/minecraft-creator (à l’aide du bouton Fork en haut à droite).

Bouton Fork GitHub

Dans le dossier «creator/Documents», sélectionnez Ajouter un fichier > Créer un nouveau fichier en haut à droite.
Créez un nom de page pour l’article (utilisez des tirets au lieu d’espaces et n’utilisez pas de ponctuation ni d’apostrophe) et ajoutez «.md»

Important

Assurez-vous de créer le nouvel article à partir du dossier «creator/Documents». Vous pouvez confirmer cette création en recherchant «/creator/Documents» dans la nouvelle ligne de nom de fichier.

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:
---

Remplissez les champs de métadonnées appropriés selon les instructions de la section ci-dessus.
Rédigez le contenu de l’article en utilisant les bases de Markdown.
Ajoutez une section ## See also au bas de l’article avec des liens vers d’autres articles pertinents.
Lorsque vous avez terminé d’écrire votre article, sélectionnez Valider un nouveau fichier.
Sélectionnez Nouvelle demande de tirage et fusionnez la branche «principale» de votre fork dans MicrosoftDocs/minecraft-creator «main» (assurez-vous que la flèche pointe dans la bonne direction).

Demande de tirage GitHub

Votre demande de tirage sera examinée par notre équipe de contenu. Si elle est approuvée, vos modifications seront mises en ligne lors de notre prochaine publication régulière. Si votre demande n’est pas approuvée, un membre de l’équipe chargée du contenu laissera un commentaire dans votre demande pour vous indiquer la raison de ce refus.

Notions de base de Markdown

Les ressources suivantes vous aideront à apprendre à modifier la documentation à l’aide du langage Markdown:

Ajouter des tableaux

En raison de la façon dont docs.microsoft.com interprète les tableaux, ceux-ci ne comporteront pas de bordures ou de styles personnalisés, même si vous utilisez le CSS intégré. Cela semblera fonctionner pendant un moment, mais la plateforme finira par retirer le style du tableau. Planifiez donc à l’avance et gardez vos tableaux simples. Voici un site qui facilite les tableaux Markdown.

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

|Title 1 |Title 2| Title 3|
|--------|-------|--------|
|This will |Show a three |column table|

Ajouter des images

Vous devrez télécharger vos images dans le dossier «minecraft-creator/creator/images» du référentiel, puis les référencer de manière appropriée dans l’article. Les images s’afficheront automatiquement en taille réelle, ce qui signifie que les grandes images rempliront toute la largeur de l’article. Nous vous recommandons de reformater vos images avant de les télécharger. La largeur recommandée est comprise entre 600 et 700pixels, mais vous devez augmenter ou diminuer la taille si la capture d’écran est dense ou si elle ne représente qu’une fraction d’une capture d’écran.

Important

Vous ne pouvez télécharger des images que sur votre référentiel forké avant de fusionner. Donc, si vous prévoyez d’ajouter des images à un article, vous devrez d’abord utiliser Visual Studio Code pour ajouter les images au dossier «images» de votre fork ou assurez-vous d’avoir effectué les opérations suivantes dans un navigateur Web:

Vous avez forké le référentiel MicrosoftDocs/minecraft-creator.
Vous avez modifié l’article dans votre fork.
Vous avez téléchargé les images que vous référencez dans votre article dans le dossier «minecraft-creator/creator/images» de votre fork.
Vous avez créé une demande de tirage pour fusionner votre fork dans la branche «principale» de MicrosoftDocs/minecraft-creator.

Pour savoir comment configurer votre propre référentiel forké, suivez les instructions de création d’un nouvel article.

Prévisualiser votre travail

Lors de l’édition dans GitHub via un navigateur Web, vous pouvez sélectionner l’onglet d’aperçu en haut de la page pour prévisualiser votre travail avant de le valider.

Notes

L’aperçu de vos modifications sur review.docs.microsoft.com n’est disponible que pour les employés de Microsoft

Employés de Microsoft: une fois vos contributions fusionnées dans la branche «principale», vous pouvez consulter le contenu avant qu’il ne soit rendu public sur https://github.com/MicrosoftDocs/minecraft-creator/tree/main/creator. Trouvez votre article en utilisant la table des matières dans la colonne de gauche.

Édition dans un navigateur Web ou avec un client de bureau?

L’édition dans le navigateur est le moyen le plus simple d’effectuer des modifications rapides, mais elle présente quelques inconvénients:

Vous ne pouvez pas utiliser un correcteur orthographique.
Vous ne bénéficiez pas de liens intelligents vers d’autres articles (vous devez saisir manuellement le nom de fichier de l’article).
Le téléchargement et le référencement des images peuvent s’avérer fastidieux.

Si vous préférez ne pas avoir à gérer ces problèmes, utilisez un client de bureau comme Visual Studio Code avec quelques extensions utiles lors de votre contribution.

Utilisation de Visual Studio Code

Pour les raisons indiqué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.

Configuration

Suivez ces étapes pour configurer Visual Studio Code afin de pouvoir utiliser ce référentiel:

Dans un navigateur Web:

a. Installez Git sur votre PC.

b. Installez Visual Studio Code.

c. Forkez MicrosoftDocs/minecraft-creator si vous ne l’avez pas déjà fait.

d. Dans votre fork, sélectionnez Cloner ou téléchargez et copiez l’URL.
Créez un clone local de votre fork dans Visual Studio Code:

a. Dans le menu Affichage, sélectionnez Palette de commandes.

b. Tapez «Git: Clone».

c. Collez l’URL que vous avez copiée.

d. Choisissez où enregistrer le clone sur votre PC.

e. Sélectionnez Ouvrir le référentiel dans la fenêtre contextuelle.

Modifier la documentation

Utilisez le workflow suivant pour apporter des modifications à la documentation avec Visual Studio Code: