Aide à la rédaction des applets de commande PowerShell

Les applets de commande PowerShell peuvent être utiles, mais à moins que vos rubriques d'aide n'expliquent clairement ce que fait l'applet de commande et comment l'utiliser, l'applet de commande risque de ne pas être utilisée ou, pire encore, elle peut frustrer les utilisateurs. Le format de fichier d'aide de l'applet de commande basé sur XML améliore la cohérence, mais une aide précieuse nécessite bien plus.

Si vous n’avez jamais rédigé d’aide sur les applets de commande, consultez les instructions suivantes. Le schéma XML requis pour créer la rubrique d'aide de l'applet de commande est décrit dans la section suivante. Commencez par créer le fichier d’aide de la cmdlet. Cette rubrique inclut une description des nœuds XML de niveau supérieur.

Directives de rédaction pour l’aide des applets de commande

Bien écrire

Rien ne remplace un sujet bien écrit. Si vous n'êtes pas un écrivain professionnel, trouvez un écrivain ou un éditeur pour vous aider. Une autre alternative consiste à copier votre texte d'aide dans Microsoft Word et à utiliser les vérifications grammaticales et orthographiques pour améliorer votre travail.

Écrivez simplement

Utilisez des mots et des expressions simples. Évitez le jargon. Considérez que de nombreux lecteurs ne disposent que d'un dictionnaire de langues étrangères et de votre rubrique d'aide.

Écrivez de manière cohérente

L'aide pour les applets de commande associées doit être similaire (par exemple, Get-Content et Set-Content). Utilisez les descriptions standard pour les paramètres standard, comme Force et InputObject. (Copiez-les depuis l'aide pour les applets de commande principales.) Utilisez des termes standard. Par exemple, utilisez « paramètre » et non « argument » et utilisez « applet de commande » et non « commande » ou « command-let ».

Commencez le synopsis par un verbe

Le champ synopsis informe l'utilisateur de ce que fait l'applet de commande, et non de ce que c'est ou de son fonctionnement. Les verbes créent une instruction basée sur une tâche qui informe les utilisateurs si cette applet de commande répond à leurs exigences. Utilisez des verbes simples comme « obtenir », « créer » et « changer ». Évitez « définir », qui peut être des mots vagues et fantaisistes comme « modifier ».

Concentrez-vous sur les objets

La plupart des applets de commande « get » affichent quelque chose, mais leur fonction principale est d'obtenir un objet. Dans votre aide, concentrez-vous sur l'objet afin que les utilisateurs comprennent que l'affichage par défaut est un parmi tant d'autres et qu'ils peuvent utiliser les méthodes et propriétés de l'objet que vous avez récupéré pour eux de différentes manières.

Rédiger des descriptions détaillées

Répertoriez brièvement tout ce que l'applet de commande peut faire dans la description détaillée. Si la fonction principale est de modifier une propriété, mais que l'applet de commande peut modifier toutes les propriétés, indiquez-la dans la description détaillée.

Utiliser une syntaxe conventionnelle

Utilisez le format standard Backus-Naur qui est courant pour l'aide en ligne de commande Windows et UNIX.

Utiliser les types Microsoft .NET pour les valeurs des paramètres

Les espaces réservés pour les valeurs des paramètres (dans la syntaxe et les descriptions des paramètres) affichent les types .NET Framework des objets que le paramètre acceptera. L'équipe PowerShell a développé cette convention pour aider à enseigner aux utilisateurs le .NET Framework.

Rédiger des descriptions complètes des paramètres

Les descriptions de paramètres doivent informer les utilisateurs sur deux choses : ce que fait le paramètre (son effet) et ce qu'ils doivent saisir pour les valeurs des paramètres.

Écrire des exemples pratiques

Les exemples doivent montrer comment utiliser tous les paramètres, mais le plus important est de montrer comment utiliser l'applet de commande dans des tâches réelles. Commencez par un exemple simple et écrivez des exemples de plus en plus complexes. Dans le dernier exemple, montrez comment utiliser l’applet de commande dans un pipeline.

Utilisez le champ Notes

Utilisez le champ Notes pour expliquer les concepts dont les utilisateurs ont besoin pour comprendre l'applet de commande. Vous pouvez également utiliser des notes pour aider les utilisateurs à éviter les erreurs courantes. Évitez les URL à mesure qu'elles changent. Fournissez plutôt aux utilisateurs les termes à rechercher.

Testez votre aide

Testez l'aide comme vous testez votre code. Demandez à vos amis et collègues de lire votre contenu d'aide et de fournir des commentaires. Vous pouvez également solliciter des commentaires auprès des groupes de discussion.

Voir aussi

Comment créer le fichier d'aide de l'applet de commande
Comment ajouter le nom et le synopsis de l'applet de commande à une rubrique d'aide de l'applet de commande
Comment ajouter la description détaillée à une rubrique d'aide d'une applet de commande
Comment ajouter une syntaxe à une rubrique d'aide d'applet de commande
Comment ajouter des paramètres à une rubrique d'aide d'applet de commande
Comment ajouter des types d'entrée à une rubrique d'aide d'applet de commande
Comment ajouter des valeurs de retour à une rubrique d'aide d'applet de commande
Comment ajouter des notes à une rubrique d'aide d'une applet de commande
Comment ajouter des exemples à une rubrique d'aide d'applet de commande
Comment ajouter des liens connexes à une rubrique d'aide d'une applet de commande
Kit de développement logiciel Windows PowerShell