Partager via

Écriture d’une aide pour les applets de commande PowerShell

  • Article

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

Si vous n’avez jamais écrit d’aide sur l’applet de commande, passez en revue 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éation du fichier d’aide de l’applet de commande. Cette rubrique inclut une description des nœuds XML de niveau supérieur.

Instructions d’écriture pour l’aide sur les applets de commande

Écrire correctement

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

Écrire simplement

Utilisez des mots et des expressions simples. Évitez le jargon. Considérez que de nombreux lecteurs sont équipés uniquement d’un dictionnaire en langue étrangère et de votre rubrique d’aide.

Écrire 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 à partir de l’aide pour les applets de commande principales.) Utilisez des termes standard. Par exemple, utilisez « parameter », et non « argument », et utilisez « cmdlet » et non « command-let » ou « command-let ».

Démarrer le synopsis avec un verbe

Le champ synopsis informe l’utilisateur de ce que fait l’applet de commande, et non de ce qu’il fonctionne ou de son fonctionnement. Les verbes créent une instruction basée sur des tâches qui informe les utilisateurs si cette applet de commande répond à leurs exigences. Utilisez des verbes simples tels que « get », « create » et « change ». Évitez « set », qui peut être vague et fantaisiste comme « modify ».

Focus sur les objets

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

Écrire des descriptions détaillées

Répertoriez brièvement tout ce que l’applet de commande peut effectuer dans la description détaillée. Si la fonction principale consiste à modifier une propriété, mais que l’applet de commande peut modifier toutes les propriétés, répertoriez-la dans la description détaillée.

Utiliser la syntaxe conventionnelle

Utilisez le format de Backus-Naur standard qui est courant pour l’aide de ligne de commande Windows et Unix.

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

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

Écrire des descriptions complètes des paramètres

Les descriptions des paramètres doivent informer les utilisateurs de deux choses : ce que fait le paramètre (son effet) et ce qu’il doit taper pour les valeurs de paramètre.

Écrire des exemples pratiques

Les exemples doivent montrer comment utiliser tous les paramètres, mais la chose la plus importante consiste à 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 l’exemple final, montre comment utiliser l’applet de commande dans un pipeline.

Utiliser 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. Au lieu de cela, fournissez aux utilisateurs des termes à rechercher.

Tester votre aide

Testez l’aide comme vous testez votre code. Avoir des amis et des collègues lire votre contenu d’aide et fournir des commentaires. Vous pouvez également solliciter des commentaires des groupes de news.

Voir aussi