Partager via

Contribution aux améliorations de la qualité

Vous n’avez pas besoin d’être un expert en matière ou un expert en documentation pour contribuer. Si vous voyez une opportunité d’améliorer la documentation, envoyez une demande de tirage avec votre proposition d’amélioration. Ce guide décrit plusieurs façons simples pour tous les utilisateurs de contribuer à des améliorations de qualité à la documentation.

Nous nous concentrons sur ces domaines de qualité :

Exemples de code de mise en forme

Tous les exemples de code doivent suivre les instructions de style pour le contenu PowerShell. Ces règles sont répétées sous forme abrégée ici pour des raisons pratiques :

  • Tous les blocs de code doivent être contenus dans une clôture de code triple backtick (```).
  • La longueur de ligne des blocs de code est limitée aux 90 caractères pour les articles de référence des cmdlets.
  • La longueur de ligne des blocs de code est limitée aux 76 caractères des about_* articles.
  • Évitez d’utiliser des caractères de continuation de ligne (`) dans des exemples de code PowerShell.
    • Utilisez le dépliage ou les opportunités naturelles de saut de ligne, comme après les caractères pipe (|), les accolades ouvrantes (}), les parenthèses (() et les crochets ([) pour limiter la longueur de la ligne.
  • Incluez uniquement l’invite PowerShell pour des exemples illustratifs où le code n’est pas destiné à être copié-collé.
  • N’utilisez pas d’alias dans des exemples, sauf si vous documentez spécifiquement l’alias.
  • Évitez d’utiliser des paramètres positionnels. Utilisez le nom du paramètre, même si le paramètre est positionnel.

Syntaxe des commandes de mise en forme

Tout le texte doit suivre les instructions de style pour le contenu de PowerShell. Ces règles sont répétées ici pour des raisons pratiques :

  • Utilisez toujours le nom complet pour les applets de commande et les paramètres. Évitez d’utiliser des alias, sauf si vous illustrez spécifiquement l’alias.
  • La propriété, le paramètre, l’objet, les noms de types, les noms de classes, les méthodes de classe doivent être en gras.
    • Les valeurs de propriété et de paramètre doivent être encapsulées dans des backticks (`).
    • Lorsque vous faites référence à des types à l’aide du style entre crochets, utilisez des backticks. Par exemple : [System.Io.FileInfo]
  • Les noms de modules PowerShell doivent être en gras.
  • Les mots clés et opérateurs PowerShell doivent être tous en minuscules.
  • Utilisez la casse appropriée (Pascal) pour les noms et paramètres de cmdlet.
  • Lorsque vous faites référence à un paramètre par nom, le nom doit être en gras.
  • Utilisez le nom du paramètre avec le trait d’union si vous illustrez la syntaxe. Encapsulez le paramètre dans les backticks.
  • Lorsque vous affichez un exemple d’utilisation d’une commande externe, l’exemple doit être encapsulé dans des backticks. Incluez toujours l’extension de fichier de la commande externe.

Pour la facilité de maintenance et la lisibilité de la source markdown pour notre documentation, nous convertissons notre documentation conceptuelle pour utiliser des références de liens plutôt que des liens inline.

Par exemple, au lieu de :

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

Cela devrait être :

The [Packages tab][01] displays all available packages in the PowerShell Gallery.

Remarque

Lorsque vous remplacez un lien en ligne, réorganisez le contenu jusqu'à 100 caractères. Vous pouvez utiliser l’extension VS Code reflow-markdown pour réagencer rapidement le paragraphe.

En bas du fichier, ajoutez un commentaire markdown avant la définition des liens.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Assurez-vous que :

  1. Chaque lien pointe vers l’emplacement approprié.
  2. Ne dupliquez pas les définitions de référence de lien. Si une définition de référence de lien existe déjà pour une URL, réutilisez la référence existante au lieu de en créer une nouvelle.
  3. Les définitions de référence de lien se trouvent au bas du fichier après le commentaire markdown et sont dans l’ordre numérique.

Vérification syntaxique Markdown

Pour n’importe quel article dans l’un des référentiels participants, l’ouverture de l’article dans VS Code affiche des avertissements de linting. Adressez l’un de ces avertissements que vous trouvez, sauf :

Vérifiez les longueurs des lignes et utilisez l’extension Reflow Markdown pour corriger les lignes longues.

Orthographe

Malgré nos meilleurs efforts, les fautes de frappe et les fautes d’orthographe passent et se retrouvent dans la documentation. Ces erreurs rendent la documentation plus difficile à suivre et à localiser. La correction de ces erreurs rend la documentation plus lisible, en particulier pour les non-anglophones qui s’appuient sur des traductions précises.

  • Last updated on