Guide du contributeur Microsoft Docs - Vue d’ensemble

Bienvenue dans le guide du contributeur docs.microsoft.com (Docs) !

Plusieurs des ensembles de documents Microsoft sont open source et hébergés sur GitHub. Certains ensembles de documents ne sont pas open source, mais plusieurs ont des référentiels publics dans lesquels vous pouvez suggérer des modifications via des requêtes de tirage. Cette approche open source simplifie et améliore la communication entre les ingénieurs produit, les équipes de contenu et les clients, et offre d’autres avantages :

  • Planification en open des dépôts open source pour obtenir du feedback permettant de savoir quels documents sont les plus demandés.
  • Révision en open des dépôts open source pour publier le contenu le plus utile lors de notre première publication.
  • Mise à jour en open des dépôts open source pour simplifier l’amélioration en continu du contenu.

L’expérience utilisateur sur docs.microsoft.com intègre directement les workflows GitHub pour être encore plus agréable. Commencez par modifier le document que vous visualisez. Apportez votre aide en révisant de nouvelles rubriques, ou signalez des problèmes de qualité.

Important

Tous les référentiels qui publient sur docs.microsoft.com ont adopté soit le Code de conduite Microsoft Open Source, soit le Code de conduite .NET Foundation. Pour plus d’informations, consultez les questions fréquentes (FAQ) sur le code de conduite. Vous pouvez aussi envoyer vos questions ou vos commentaires à opencode@microsoft.com ou à conduct@dotnetfoundation.org.

Les corrections mineures ou les clarifications pour la documentation, ainsi que les exemples de code dans les référentiels publics, sont couverts par les Conditions d’utilisation du site web docs.microsoft.com. Les nouveautés ou modifications significatives génèrent un commentaire dans la demande de tirage (pull request) qui vous invite à signer un contrat de licence de contribution en ligne si vous n’êtes pas un employé de Microsoft. Vous devrez remplir le formulaire en ligne pour que nous puissions examiner ou accepter votre demande de tirage (pull request).

Modifications rapides de documents existants

Les modifications rapides permettent de rationaliser le processus de signalement et de correction de petites erreurs et omissions dans des documents. Malgré tous nos efforts, les documents que nous publions peuvent contenir de petites fautes de grammaire et d’orthographe. Même si vous pouvez signaler des problèmes et nous faire part d’erreurs, il est plus rapide et plus facile de créer une demande de tirage (pull request) pour résoudre un problème lorsque l’option est disponible.

  1. Certaines pages de documents vous permettent de modifier le contenu directement dans le navigateur. Dans ce cas, un bouton Edit (Modifier) comme celui illustré ci-dessous s’affiche. En cliquant sur le bouton Edit (Modifier) , vous accédez au fichier source sur GitHub. Si le bouton Modifier est absent, cela signifie que la page de documentation ne peut pas être modifiée.

    Emplacement du lien de modification

    Si le bouton Modifier n’apparaît pas, cela signifie que le contenu n’est pas ouvert aux contributions publiques.

  2. Sélectionnez l’icône en forme de crayon pour modifier l’article. Si l’icône représentant un crayon est grisée, vous devez vous connecter à votre compte GitHub ou créer un compte.

    Emplacement de l’icône de crayon

  3. Effectuez des modifications dans l’éditeur web. Cliquez sur l’onglet Preview changes (Aperçu des modifications) pour vérifier la mise en forme de votre modification.

  4. Une fois vos modifications effectuées, faites défiler vers le bas de la page. Entrez un titre et une description de vos modifications et cliquez sur Propose file change (Proposer une modification du fichier) comme indiqué sur la figure suivante :

    Proposer une modification de fichier

  5. À présent que vous avez proposé votre modification, vous devez demander aux propriétaires du référentiel de « tirer (pull) » vos modifications dans leur référentiel. Pour cela, vous utilisez une « requête de tirage (pull) ». Lorsque vous sélectionnez Proposer une modification de fichier, une nouvelle page semblable à la suivante s’affiche :

    create pull request (créer une requête de tirage)

    Sélectionnez Créer une requête de tirage (pull) , entrez un titre (et une description, si vous le souhaitez) pour la requête de tirage, puis sélectionnez Créer une requête de tirage (pull) . Si vous débutez avec GitHub, consultez About Pull Requests pour plus d’informations.

  6. Et voilà ! Les membres de l’équipe de contenu réviseront et fusionneront votre demande de tirage (PR) lorsqu’ils l’auront approuvée. Il est possible que vous receviez des suggestions de modifications.

L’interface utilisateur de modification GitHub est fonction de vos autorisations dans le référentiel. Les images précédentes concernent les contributeurs qui n’ont pas d’autorisations d’écriture pour le référentiel cible. GitHub crée automatiquement une duplication (fork) du référentiel cible dans votre compte. Si vous bénéficiez d’un accès en écriture au dépôt cible, GitHub y crée une nouvelle branche. Le nom de la branche a la structure <GitHubId>-patch-n, avec votre identifiant GitHub et un identificateur numérique pour la branche du correctif.

Nous utilisons des demandes de tirage (PR) pour toutes les modifications, même pour les contributeurs bénéficiant d’un accès en écriture. La branche par défaut de la plupart des dépôts étant protégée, les mises à jour doivent êtres envoyées sous forme de demandes de tirage (PR).

L’expérience de modification dans le navigateur est la mieux adaptée à des modifications mineures ou peu fréquentes. Si vous effectuez des contributions importantes ou que vous utilisez des fonctionnalités avancées de Git (comme la gestion des branches ou la résolution des conflits de fusion avancés), vous devez dupliquer le dépôt et travailler localement.

Notes

Le plus souvent, la documentation localisée ne permet pas d’apporter des modifications ou de fournir des commentaires par le biais de GitHub. Pour fournir des commentaires sur le contenu localisé, vous devez utiliser le modèle d’e-mail disponible ici : aka.ms/DocSiteLocFeedback. Il existe cependant une exception dans la documentation Azure. Certains dépôts GitHub publics localisés pour azure-docs acceptent les contributions de la communauté, et ce, dans 6 langues : Chinois simplifié, Français, Allemand, Japonais, Coréen et Espagnol. Pour toutes les autres langues et ensembles de contenu, vous devez utiliser le modèle d’e-mail (qui vous permet d’écrire dans votre propre langue) pour signaler des problèmes de traduction ou pour fournir des commentaires techniques.

Revue des demandes de tirage (PR) ouvertes

Vous pouvez lire les nouvelles rubriques avant leur publication en consultant les demandes de tirage (PR) actuellement ouvertes. Les révisions suivent le processus de flux GitHub. Vous pouvez voir les mises à jour proposées ou les nouveaux articles dans les référentiels publics. Révisez-les et ajoutez vos commentaires. Parcourez l’un de nos référentiels de documents pour consulter les demandes de tirage (PR) ouvertes des zones qui vous intéressent. Les commentaires de la communauté sur des mises à jour proposées aident toute la communauté virtuelle.

Signaler des problèmes de qualité

Nos documents font l’objet d’un travail continu. Les problèmes pertinents nous aident à concentrer nos efforts sur les priorités absolues de la communauté virtuelle. Plus vous pouvez fournir de détails, plus la signalisation du problème sera utile. Dites-nous quelles informations vous avez cherchées. Dites-nous quels termes vous avez utilisés pour la recherche. Si vous n’arrivez-pas à la lancer, dites-nous comment vous souhaitez commencer à explorer une technologie qui ne vous est pas familière.

La plupart des pages de la documentation Microsoft contiennent une section Commentaires au bas de la page sur laquelle vous pouvez cliquer pour laisser des commentaires sur le produit ou des commentaires sur le contenu afin d’effectuer le suivi des problèmes spécifiques à cet article.

Les problèmes permettent d’amorcer une conversation sur ce dont vous avez besoin. L’équipe chargée du contenu réagira aux problèmes signalés avec des idées concernant ce que nous pouvons ajouter et vous demandera votre avis. Lorsque nous créons un brouillon, nous vous demandons de réviser la demande de tirage (PR).

Engagez-vous plus

D’autres rubriques vous aident à commencer à contribuer de manière productive à Microsoft Docs. Elles expliquent les extensions utilisées sur la plateforme Microsoft Docs, ainsi que l’utilisation des référentiels GitHub et des outils Markdown.