Commencez à contribuer à la documentation de PowerShell

Cet article est une vue d’ensemble de la prise en main en tant que contributeur à la documentation PowerShell.

Structure de PowerShell-Docs

Il existe trois catégories de contenu dans le référentiel PowerShell-Docs :

• contenu de référence
• contenu conceptuel
• métadonnées et fichiers de configuration

Contenu de référence

Le contenu de référence correspond aux informations de référence sur les cmdlets fournies avec PowerShell. La référence de l'applet de commande est collectée dans les dossiers versionnés (comme 5.1, 7.4, 7.5 et 7.6), qui contiennent les références des modules fournis avec PowerShell. Ce contenu est également utilisé pour créer les informations d’aide affichées par l’applet de commande Get-Help.

Contenu conceptuel

La documentation conceptuelle n’est pas organisée par version. Tous les articles sont affichés pour chaque version de PowerShell.

Remarque

Chaque fois qu’un article conceptuel est ajouté, supprimé ou renommé, la table des matières doit être mise à jour. Tous les fichiers supprimés ou renommés doivent être redirigés.

Fichiers de métadonnées

Ce projet contient plusieurs types de fichiers de métadonnées. Les fichiers de métadonnées contrôlent le comportement de nos outils de génération et du système de publication. Seuls les mainteneurs PowerShell-Docs et les contributeurs approuvés sont autorisés à modifier ces fichiers. Si vous pensez qu’un métafichier doit être modifié, ouvrez un problème pour discuter des modifications nécessaires.

Fichiers meta à la racine du référentiel

• .* : fichiers de configuration à la racine du référentiel
• *.md - Documentation du projet à la racine du dépôt
• *.yml - Documentation du projet à la racine du dépôt
• .devcontainer/* - fichiers de configuration devcontainer
• .github/**/* - Modèles, actions et autres fichiers meta GitHub
• .vscode/**/* - Configurations d’extension VS Code
• assets/* : contient des fichiers téléchargeables liés dans la documentation
• redir/* : contenir des fichiers de mappage de redirection
• tests/* - outils de test utilisés par le système de génération
• tools/* - autres outils utilisés par le système de génération

Fichiers Meta dans l'ensemble de documentation

• reference/**/*.json : fichiers de configuration docset
• reference/**/*.yml - TOC et d’autres fichiers de contenu structurés
• reference/bread/* : configuration de la navigation la barre de navigation
• reference/includes/* : fichiers include Markdown
• reference/mapping/* - Configuration du mappage de version
• reference/**/media/** - fichiers image utilisés dans la documentation
• reference/module/* : configuration de la page Explorateur de modules

Création d’articles

Vous devez créer un problème GitHub pour chaque document que vous souhaitez ajouter. Vérifiez les problèmes existants pour vous assurer que vous ne dupliquerez pas les efforts. Les problèmes attribués sont considérés comme in progress. Si vous souhaitez collaborer sur un problème, contactez la personne affectée au problème.

Comme pour le processus RFC powerShell , créez un problème avant d’écrire le contenu. Le problème permet d'éviter de perdre du temps et bien des efforts sur des travaux qui sont rejetés par l'équipe de PowerShell-Docs. Le problème nous permet de vous consulter sur l’étendue du contenu et son emplacement dans la documentation PowerShell. Tous les articles doivent être inclus dans la table des matières (TOC). L’emplacement du TOC proposé doit être inclus dans la discussion sur le problème.

Remarque

Le système de publication génère automatiquement une Table des matières pour les contenus de référence. Vous n’avez pas besoin de mettre à jour la table des matières.

Mise à jour d’articles existants

Le cas échéant, les articles de référence des applets de commande sont dupliqués dans toutes les versions de PowerShell conservées dans ce référentiel. Lorsque vous signalez un problème à propos d’une référence d’applet de commande ou d’un article About_, répertoriez les versions de l’article qui présentent le problème.

Appliquez la modification appropriée à chaque version du fichier.

Contenu localisé

La documentation PowerShell est écrite en anglais et traduite en 17 autres langues. Le contenu anglais est stocké dans le référentiel GitHub nommé MicrosoftDocs/PowerShell-Docs. Les problèmes trouvés dans le contenu traduit doivent être envoyés à ce référentiel.

Toutes les traductions commencent d’abord par le contenu anglais. Nous utilisons à la fois la traduction humaine et automatique.

Méthode de traduction	Langues
Traduction humaine	de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, zh-CN, zh-TW
Traduction automatique	cs-CZ, hu-HU, nl-NL, pl-PL, pt-PT, sv-SE, tr-TR

Le contenu traduit par la traduction automatique peut ne pas toujours entraîner de choix de mots et de grammaire corrects. Si vous trouvez une erreur dans la traduction pour une langue quelconque, plutôt que dans les détails techniques de l’article, ouvrez un problème expliquant pourquoi vous pensez que la traduction est incorrecte.

Certains problèmes de traduction peuvent être résolus en modifiant les fichiers sources anglais. Toutefois, certains problèmes peuvent nécessiter des mises à jour de notre système de traduction interne. Pour ces cas, nous devons soumettre le problème à notre équipe de localisation interne pour examen et réponse.

Étapes suivantes

Il existe deux façons courantes d’envoyer des modifications dans GitHub. Les deux méthodes sont décrites dans le Guide du contributeur central :

1. Vous pouvez apporter des modifications rapides aux documents existants dans l’interface web GitHub.
2. Utilisez le flux de travail GitHub complet pour ajouter de nouveaux articles, mettre à jour plusieurs fichiers ou d’autres modifications importantes.

Avant de commencer les modifications, vous devez créer un fork du référentiel PowerShell-Docs. Les modifications doivent être apportées dans une branche de travail dans votre copie de PowerShell-Docs. Si vous utilisez la méthode de modification rapide dans GitHub, ces étapes sont gérées pour vous. Si vous utilisez le workflow GitHub complet, vous devez avoir une configuration pour travailler localement.

Les deux méthodes se terminent par la création d'une Pull Request (PR). Pour plus d’informations et de bonnes pratiques, consultez Soumettre une pull request.