Comment écrit-on de bons messages d’erreur?

Bien qu’il s’agisse davantage d’un problème de langage écrit que d’un problème de codage, les programmeurs doivent le faire dans des circonstances où la copie n’est pas fournie par un client ou par quelqu’un d’autre. Tous les exemples de messages d’erreur, bons ou mauvais, sont les bienvenus.

J’ai brièvement cherché et n’ai pas pu trouver un fil de dupe. Ok, allez-y. Merci a tous.

    • S’excuser.
    • Dites ce qui a mal tourné.
    • Dites comment le résoudre.
    • Sois poli.
    • Le message doit être libellé de manière à ce que l’application accepte la responsabilité du problème. Ne jamais blâmer ou critiquer l’utilisateur ou lui faire croire que c’est sa faute.

    Exemple:
    “Désolé, le fichier n’a pas pu être ouvert. Veuillez vérifier que le fichier n’est pas déjà ouvert par un autre programme et réessayer.”

    S’il y a des détails supplémentaires qui feraient peur à l’utilisateur, comme un numéro d’erreur ou quelque chose que seul un développeur comprendrait, ne les affichez pas. Ecrivez-les dans un fichier journal ou appuyez sur un bouton Détails pour y accéder.

    Je suppose que vous parlez de montrer des messages d’erreur aux utilisateurs dans les boîtes de message ou à l’écran.

    Voulez-vous dire face à l’utilisateur ou dans un fichier journal pour le personnel admin / dev?

    Je pense que ce sont importants, en général:

    • Horodatage
    • Degré de gravité
    • ce qui a mal tourné
    • Répondez aux questions “dois-je agir?” et “si oui, quelles actions?”
    • détail au niveau du dev (pas très visible, face à l’utilisateur)
    • format et termes cohérents

    Je pense que tout cela est important, mais l’importance changera en fonction de l’audience (comme le souligne Dmckee). Une autre astuce (en général) est de répondre aux 5 W (who, what, … etc)

    Je travaille dans une entreprise de sécurité logicielle, donc ma réponse peut être très différente de certaines des réponses ci-dessus.

    Un bon message d’erreur de l’utilisateur est:

    Équilibre entre être générique et spécifique – Vous voulez donner à l’utilisateur suffisamment d’informations pour corriger son erreur et aller de l’avant, mais n’oubliez pas qu’un attaquant pourrait utiliser ces mêmes messages d’erreur pour attaquer votre site. Un bon exemple de ceci est un contrôle de connexion dans lequel un message d’erreur est renvoyé «mot de passe incorrect pour l’utilisateur joe» ou «l’utilisateur joe n’existe pas dans ce système». Cela indique à l’attaquant qu’il est en train de trouver des utilisateurs corrects. Qui quand vous n’avez ni nom d’utilisateur ni mot de passe, c’est la moitié de la bataille.

    Indique à l’utilisateur ce qui n’a pas fonctionné – encore une fois, ceci est équilibré entre générique et spécifique. Un utilisateur n’a jamais besoin de voir un message d’erreur ODBC, mais il peut être utile qu’il sache que l’erreur est de votre faute et qu’il doit réessayer dans quelques minutes. Indiquez à l’utilisateur ce qu’il peut faire pour vous aider – si vous avez un système de journalisation dorsal (que vous devriez) consigner tout ce que vous pensez être utile, générez ensuite un ID que vous pourrez fournir à l’utilisateur pour qu’il vous appelle et vous dire exactement les étapes de repro. Vous pouvez également automatiser cela en exposant un formulaire de soumission de bogue lorsqu’une erreur survient.

    Soyez cohérent – utilisez une table de recherche d’erreur pour vous assurer que toutes vos erreurs sont les mêmes (pour le même problème) et qu’elles sont bien écrites. Les fautes de frappe, les fautes d’orthographe et les erreurs grammaticales ne peuvent pas être tolérées dans les logiciels de production.

    Pour les utilisateurs finaux: Dites à l’utilisateur quoi faire. Si l’utilisateur modifie une valeur d’entrée, réessayez dans 5 minutes ou appelez le support?

    Un bon message d’erreur comporte trois parties:

    1. Le problème – explique qu’une erreur est survenue;
    2. La cause – explique ce qui a causé le problème;
    3. La solution – explique comment surmonter le problème.

    Si vous écrivez ou révisez votre message d’erreur, concentrez-vous d’abord sur l’obtention de ces trois points. Même si le message est terriblement long, ne vous en faites pas pour la première fois. Vous pouvez toujours revenir en arrière et le simplifier plus tard.

    Mais le contraire n’est pas vrai. Il est difficile de former un petit message en un message expliquant clairement le problème, la cause et la solution du problème. Vous réviserez constamment vos pensées pour vous assurer que le message rest petit et que, à un moment donné, vous serez bloqué. Oui, j’ai rencontré ce problème à plusieurs resockets, alors je sais à quel point c’est difficile.

    Après vous être assuré que votre message contient toutes ces trois parties, il est temps de l’examiner. Vous devez le modifier pour vous en assurer:

    1. Est centré sur l’utilisateur – évitez le jargon et les mots que votre public aura du mal à comprendre;
    2. Est direct – comme l’a dit William Strunk: «Mettez les déclarations sous une forme positive. Évitez le langage apprivoisé, incolore, hésitant et sans engagement »;
    3. Omet de mots inutiles – couper, couper, couper.

    Comme vous pouvez le constater, ce cadre est simple et n’a pas besoin de beaucoup de reflection.

    Sources:

    Évidemment, la prévention des erreurs est la meilleure. Fournissez toujours à l’utilisateur des informations suffisantes pour mener à bien les tâches (par exemple, expliquez le formatage requirejs dans les champs de saisie de données). Cependant, “l’erreur est humaine …” et (en appliquant les principes de la facilité d’utilisation aux erreurs dans une application Web), le but est de pardonner.

    Les messages d’erreur comportent trois fonctions essentielles:

    1. attirer l’attention – d’abord, pour assurer l’efficacité, l’utilisateur doit le voir

    • La couleur rouge)
    • police (taille, poids)
    • emplacement (haut de la page, boîte d’alerte)
    • focus (symbole!, contour de la zone de saisie)
    • cohérence (utiliser un format similaire pour les messages d’erreur dans toute l’application)

    2. Décrivez l’erreur – informez l’utilisateur de ce qui ne va pas

    • utiliser un langage clair que l’utilisateur comprend
    • utiliser la voix objective, ne pas blâmer l’utilisateur
    • être concis

    3. Proposer une récupération – donner des suggestions utiles pour corriger l’erreur et continuer

    • préserver tout ce que l’utilisateur a accompli jusqu’à présent
    • réduire le travail nécessaire pour le corriger
    • pour l’utilisateur connecté, autoriser la réauthentification à l’expiration du délai

    Cela dit, j’aimerais bien comstackr quelque chose avec plus de détails, et en particulier avec des exemples de messages d’erreur bons et mauvais.

    Pour écrire de bons messages d’erreur, vous devez réfléchir à chaque audience. Une fois que vous avez compris le public, il est beaucoup plus facile de concevoir les messages d’erreur.

    Tout d’abord, les exigences pour les messages de l’utilisateur final:

    • Veut effectuer une tâche
    • Veut savoir sur les solutions, pas sur les problèmes
    • Ne veut pas réellement voir ou lire les messages d’erreur.

    Ensuite, les exigences pour les messages de technicien de support:

    • Veut être proactif, pas réactif
    • Ne veut pas bash un problème de «mur de briques»
    • Ne veut pas être inondé de messages.

    Enfin, les exigences pour les messages de développeur de support:

    • Veut un modèle mental simple pour utiliser votre code
    • Attend que votre composant «fonctionne»
    • Veut des informations utiles quand ça ne marche pas.

    Un exemple de message d’erreur qui est très mauvais pour un utilisateur final, mais qui peut être raisonnable pour un développeur, est “Le cache de latence est entré en collision avec les en-têtes sortants”. 🙂

    À ce qui a déjà été dit, j’appendais:

    • Ne présentez aucun message pouvant constituer un risque de sécurité, comme des mots de passe ou autres. Ceci est particulièrement important pour les applications Web, lorsque de telles choses ne sont pas déjà disponibles lors de la décompilation.
    • S’il vous plaît avoir tout texte lisible par l’utilisateur, si vous n’êtes pas déjà une grammaire obsessionnelle et orthographe maven.

    Les messages d’erreur doivent:

    • Soyez précis sur la cause de l’erreur.
    • Proposez des suggestions pour corriger l’erreur.
    • N’utilisez pas de mots qui confondent l’utilisateur moyen.

    Du sharepoint vue de l’assistance technique, il est également important que les messages d’erreur soient uniques. Si un utilisateur peut générer le même erreur “fichier ne peut pas être ouvert” de six manières différentes, il est difficile pour les techniciens de déterminer exactement ce que fait l’utilisateur. Ainsi, les messages d’erreur doivent être uniques pour chaque type d’erreur et, si possible, fournir un code ou un numéro d’erreur afin que les utilisateurs puissent savoir où trouver le problème.

    Nous avons constaté que lorsque les messages d’erreur incluent un code d’erreur, cela aide le support technique. Lorsque les utilisateurs signalent des messages d’erreur pour aider les utilisateurs, ils confondent souvent ou signalent des messages d’erreur verbaux. Mais si le message comporte un numéro d’erreur, ils sont très efficaces pour signaler l’erreur exacte, comme “j’ai eu une erreur 8512 lorsque j’ai essayé d’imprimer un rapport”.

    Lorsque cela est possible, cela aide aussi à garder un journal des erreurs. Souvent, les utilisateurs signalent des erreurs lorsqu’ils ont tenté une opération particulière, mais ils ne se souviendront pas exactement de l’erreur. Si un journal des erreurs peut être consulté par des techniciens, il est beaucoup plus facile de déterminer le problème.

    Cela vaut généralement la peine de souligner une raison courante du problème, car cela aidera l’utilisateur dans 99,9% des cas d’erreur.

    Par exemple, nous avons deux directions pour les problèmes d’initialisation. On attrape des exceptions de configuration qui stipule:

    “Une exception reconnue s’est produite. Cela peut être un problème avec la configuration”

    et un autre pour inattendu:

    “Une erreur inattendue s’est produite.”

    Ensuite, en fonction du paramètre (activation ou désactivation de dev), nous produisons des informations sur les développeurs ou des informations plus conviviales pour les utilisateurs finaux.

    Les messages d’erreur sont destinés aux utilisateurs finaux et à ceux qui doivent conserver le code

    Tout d’abord pour les utilisateurs finaux, leur dire quoi faire. Cela peut simplement appuyer sur Entrée pour continuer, pour réessayer, pour fermer et redémarrer, pour redémarrer le PC.

    Deuxièmement, pour les responsables, incluez autant d’informations que possible sur l’erreur. Il n’y en a jamais trop. Je préfère personnellement un fichier journal pour cela au lieu d’un message d’erreur. Encore mieux est d’inclure un moyen pour l’utilisateur final de vous envoyer par courrier électronique le contenu du journal à partir de l’application.

    Si vous pouvez indiquer à l’utilisateur quoi faire, veuillez envisager de le faire par programmation. À mon avis, les messages d’erreur ne devraient apparaître que si le programme a des doutes sur la marche à suivre. Pensez à la raison pour laquelle vous avez décidé d’échouer: peut-être ne pas prendre la responsabilité d’essayer de récupérer? Peut-être que l’utilisateur peut le faire beaucoup plus facilement? Peut-être que l’utilisateur doit décider quelle solution prendre? Peut-être avez-vous pensé que cela ne devrait jamais arriver (n’oubliez pas de demander à l’utilisateur de contacter le support ou le programmeur dans ce cas)?

    Une chose qui peut endommager mon système nerveux est quand un message d’erreur utilise le mot OU. “Fichier introuvable OU pas de permission OU disque plein OU votre chien a mal à la tête OU …” Un utilisateur a vraiment besoin de savoir laquelle des causes possibles de l’erreur est arrivée. Les programmeurs évitent les OR dans les messages d’erreur.

    Ne copiez pas les messages d’erreur à différents endroits du code. Si un utilisateur voit le message dans votre programme et envoie des commentaires, le cas le plus opportun est de savoir ce que signifiait votre message d’erreur. Le cas le moins chanceux est que vous pouvez au moins graver l’intégralité du code source et trouver l’endroit où le programme est tombé en panne. Si vous trouvez le même message à plusieurs endroits, vous ne pouvez pas vous aider.

    Oh, et n’oubliez pas de mentionner les conséquences possibles: “Le système de prévention des écureuils a cessé de fonctionner. Tout ce qui est stocké sur vos disques durs peut être modifié aléatoirement par les écureuils.” “Le système de prévention des écureuils a cessé de fonctionner. Le cadre général de prévention empêchera plutôt les écureuils.” Il y a une différence dans la sévérité.

    Rappelez-vous avant tout que l’utilisateur final ne se soucie pas de la réalité technologique. Seulement si ça marche. Quand cela ne fonctionne pas, il ou elle ne se soucie que de ses effets sur ce qu’ils essaient de faire. Un message d’erreur utile devrait restr concentré sur le quoi , pas le pourquoi .

    Il peut y avoir quelques contextes différents à noter ici (même si je suis sûr que cela a été mentionné à maintes resockets):

    1) Si nous parlons d’un site web devant donner un message “Oups, quelque chose de grave est arrivé”, alors il devrait y avoir un langage simple pour indiquer à l’utilisateur qu’une erreur est survenue. Veuillez réessayer et contacter le support bla bla bla …

    2) Si nous parlons de la journalisation d’une exception générée dans le code pour que les administrateurs système et les développeurs puissent la lire, le problème consiste à enregistrer le message et la trace de la stack dans un fichier journal, un courrier électronique ou un événement. spectateur afin qu’il puisse être traité différemment en fonction de l’urgence de la situation.

    3) Si nous parlons d’écrire le message pour une exception, alors je suggère de noter clairement quel type d’erreur a été rencontré, par exemple, y a-t-il une référence nulle où il ne devrait pas y avoir ou est-ce que quelque chose exist est manquant, avec la gravité de l’erreur, par exemple l’application peut-elle continuer à fonctionner ou doit-elle sortir sur une page d’erreur dans cette condition?

    De la perspective des utilisateurs.