usability - friendly - ¿Cómo se pueden escribir buenos mensajes de error?

error messages best practices (15)

¿Te refieres al usuario o en un archivo de registro para el personal de administración / desarrollo?

Creo que estos son importantes, en general:

Marca de tiempo
Nivel de severidad
qué salió mal
Responda las preguntas "¿Debo tomar medidas?" y "si es así, ¿qué acción?"
detalle del nivel de desarrollo (no de forma destacada, si está orientado al usuario)
formato y términos consistentes

Creo que todos estos son importantes, pero la prominencia cambiará dependiendo de la audiencia (como señala dmckee). Otro consejo (en general) es responder a las 5 W (quién, qué, ... etc.)

Si bien este es más un problema de lenguaje escrito que uno de codificación, es algo que los programadores deben hacer en circunstancias en las que un cliente u otra persona no proporcionen copia. Todos los ejemplos de mensajes de error, buenos o malos, son bienvenidos para aclarar el punto.

Busqué brevemente y no pude encontrar un hilo de engaño. Ok, hazlo. Gracias a todos.

Los mensajes de error deberían:

Sea específico sobre qué causó el error.
Ofrezca sugerencias para corregir el error.
No use palabras que confundan al usuario promedio.

Desde un punto de voz de soporte técnico, también es importante que los mensajes de error sean únicos. Si un usuario puede generar el mismo error de "archivo no se puede abrir" de seis maneras diferentes, dificulta que las personas de soporte técnico averigüen exactamente qué está haciendo el usuario. Por lo tanto, los mensajes de error deben ser únicos para cada tipo diferente de error y, si es posible, proporcione un código o número de error para que las personas de soporte sepan dónde buscar el problema.

Hemos encontrado que cuando los mensajes de error incluyen un código de error, ayuda con el soporte técnico. Cuando los usuarios informan los mensajes de error a las personas de apoyo, a menudo mezclan o informan mal los mensajes de error verbales. Pero, si el mensaje incluye un número de error, son muy buenos para informar el error exacto, como "Recibí un error 8512 cuando traté de imprimir un informe".

Cuando sea posible, también ayuda a mantener un registro de errores. Muchas veces los usuarios reportarán errores cuando probaron una operación en particular, pero no recordarán exactamente cuál fue el error. Si hay un registro de errores que puede ser consultado por personal de soporte técnico, es mucho más fácil determinar el problema.

Para usuarios finales: dígale al usuario qué hacer. Si el usuario cambia algún valor de entrada, vuelva a intentarlo en 5 minutos o llame al servicio de asistencia técnica.

Recuerde sobre todo que al usuario final no le importa el elemento tecnológico. Solo si funciona Cuando no funciona, solo se preocupa por su efecto sobre lo que están tratando de hacer. Un mensaje de error útil debe centrarse en el qué , no el por qué .

Trabajo en una firma de seguridad de software, por lo que mi respuesta puede ser significativamente diferente de algunas de las respuestas anteriores.

Un mensaje de error de buen usuario es:

Equilibrado entre ser genérico y específico: desea brindarle al usuario la información suficiente para que pueda corregir su error y seguir adelante, pero tenga en cuenta que un atacante podría usar estos mismos mensajes de error para atacar su sitio. Un buen ejemplo de esto es un control de inicio de sesión en el que se devuelve un mensaje de error "contraseña incorrecta para el usuario joe" o "el usuario joe no existe en este sistema" le dice al atacante que están en la ruta de descubrir usuarios correctos. Que cuando no tienes un nombre de usuario o una contraseña es la mitad de la batalla.

Le dice al usuario qué fue lo que salió mal. De nuevo, esto se equilibra entre genérico y específico. Un usuario nunca necesita ver un mensaje de error de ODBC, pero podría serle útil saber que el error fue su culpa y que debería volver a intentarlo en unos minutos. Dígale al usuario qué pueden hacer para ayudarlo: si tiene un sistema de registro de back-end (que debería), debe registrar todo lo que considere útil, luego genere una identificación que pueda proporcionar al usuario para que puedan llamarlo o enviarle un correo electrónico y te digo pasos exa exactos. También puede automatizar esto al exponer un formulario de envío de errores cuando ocurre un error.

Sea consistente: use una tabla de búsqueda de errores para asegurarse de que todos sus errores sean los mismos (para el mismo problema) y de que estén bien escritos. Typos, errores ortográficos y errores gramaticales no pueden ser tolerados en el software de producción.

Pedir disculpas.
Di lo que salió mal.
Di cómo resolverlo.
Ser cortés.
El mensaje debe estar redactado para que la aplicación acepte la responsabilidad del problema. Nunca culpe o critique al usuario o haga que piense que es su culpa.

Ejemplo:
"Lo siento, el archivo no se pudo abrir. Verifique que el archivo no haya sido abierto por otro programa y vuelva a intentarlo".

Si hay detalles adicionales que podrían asustar al usuario, como un número de error u otra cosa que solo un desarrollador entendería, no los muestre. Escríbalas en un archivo de registro o tenga un botón de detalles que pueda presionar para llegar a ellas.

Supongo que está hablando de mostrar mensajes de error a los usuarios en cuadros de mensaje o en la pantalla.

Para escribir buenos mensajes de error, debe pensar en cada audiencia. Una vez que comprenda a la audiencia, es mucho más fácil diseñar los mensajes de error.

Primero, requisitos para los mensajes del usuario final:

Quiere realizar una tarea
Quiere saber sobre soluciones, no sobre problemas
En realidad, no quiere ver o leer mensajes de error.

A continuación, requisitos para los mensajes del técnico de soporte:

Quiere ser proactivo, no reactivo
No quiere golpear un problema de "pared de ladrillos"
No quiere ser inundado con mensajes.

Finalmente, requisitos para los mensajes de desarrollador de soporte:

Quiere un modelo mental simple para usar su código
Espera que tu componente "solo funcione"
Quiere información útil cuando no funciona.

Un ejemplo de un mensaje de error que es muy malo para un usuario final, pero que podría ser razonable para un desarrollador, es "La memoria caché de latencia colisionó con los encabezados de salida". :-)

A lo que ya se dijo agregaría:

No presente ningún mensaje que pueda ser un riesgo para la seguridad, como contraseñas y demás. Esto es especialmente importante para las aplicaciones web, cuando tales cosas aún no están disponibles a través de la descompilación.
Por favor, tenga todo el texto corregido por el usuario corregido, si usted no es ya un obsesivo gramática y ortografía.

Del prospecto de los usuarios.

Los mensajes de error son para usuarios finales y también para aquellos que tienen que mantener el código

Primero para los usuarios finales, dígales qué hacer. Esto simplemente puede presionar enter para continuar, volver a intentarlo, cerrar y reiniciar, para reiniciar la PC.

Segundo para los mantenedores, incluya tanta información sobre el error como pueda. Nunca hay demasiado Personalmente prefiero un archivo de registro para esto en lugar de un mensaje de error. Aún mejor es incluir una forma para que el usuario final le envíe por correo electrónico el contenido del registro desde la aplicación.

Por lo general, vale la pena señalar una razón común para el problema, ya que esto ayudará al usuario en el 99,9% de los casos de error.

Por ejemplo, tenemos dos direcciones para problemas de inicialización. Uno detecta excepciones de configuración que dice:

"Se produjo una excepción reconocida. Esto puede ser un problema con la configuración"

y otro para inesperado:

"Ocurrió un error inesperado".

Luego, dependiendo de la configuración (interruptor de activación o desactivación), podemos generar información de desarrollo o más información útil para el usuario final.

Puede haber algunos contextos diferentes aquí para notar (aunque estoy seguro de que esto ha sido mencionado una y otra vez):

1) Si estamos hablando de un sitio web que tiene que dar un mensaje "Oops, algo malo pasó", debería haber un lenguaje simple para decirle al usuario que se produjo un error. Inténtelo de nuevo y si todavía hay problemas para ponerse en contacto con el servicio de asistencia técnica. bla, bla, bla...

2) Si estamos hablando de registrar una excepción en el código para que los administradores de sistema y los desarrolladores la lean, la cuestión pasa a tomar el mensaje de la excepción y el seguimiento de la pila para grabarse en un archivo de registro, un correo electrónico o el evento visor para que se pueda manejar de manera diferente según cuán urgente sea que alguien mire esto.

3) Si estamos hablando de escribir el mensaje para una excepción, entonces mi sugerencia es señalar claramente qué tipo de error se cumplió, por ejemplo, hay una referencia nula donde no debería haber o hay algo peor, como un archivo que debería Existe falta, junto con la gravedad del error, por ejemplo, puede la aplicación seguir funcionando o debería salir a una página de error en esta condición.

Obviamente, la prevención de errores es lo mejor. Siempre proporcione al usuario con suficientes pistas para completar con éxito las tareas (es decir, explique el formato requerido en los campos de entrada de datos). Sin embargo, "Errar es humano ..." y (aplicando los principios de usabilidad a los errores en una aplicación web) el objetivo es el perdón.

Hay tres funciones esenciales para los mensajes de error:

1. Obtenga atención : primero, para garantizar la efectividad, el usuario debe verla

color rojo)
fuente (tamaño, peso)
ubicación (parte superior de la página, cuadro de alerta)
foco (! símbolo, esquema del cuadro de entrada)
consistencia (use un formato similar para los mensajes de error en toda la aplicación)

2. Describa el error : informe al usuario de lo que salió mal

use un lenguaje sencillo que el usuario entienda
usa voz objetiva, no culpes al usuario
sé conciso

3. Sugerir recuperación : brinde sugerencias útiles para corregir el error y continúe

preservar todo lo que el usuario haya completado hasta ahora
reducir el trabajo necesario para corregirlo
para el usuario que ha iniciado sesión, permita la nueva autenticación en el tiempo de espera

Dicho todo esto, me gustaría compilar algo con más detalle, y especialmente con ejemplos de mensajes de error buenos y malos.

Si puede decirle al usuario qué hacer, considere hacerlo de forma programática. En mi opinión, los mensajes de error solo deberían aparecer si el programa tiene dudas sobre qué hacer. Piense en por qué decidió simplemente fracasar: ¿tal vez no asumir la responsabilidad de tratar de recuperarse? Tal vez el usuario puede hacerlo mucho más fácil? ¿Tal vez el usuario tiene que decidir qué solución tomar? Tal vez pensó que nunca debería suceder (no se olvide de decirle al usuario que se comunique con el soporte o el programador en este caso).

Una cosa que puede dañar mi sistema nervioso es cuando un mensaje de error usa la palabra O. "Archivo no encontrado O ningún permiso O disco lleno O su perro tiene un fuerte dolor de cabeza O ..." Un usuario realmente necesita saber cuál de las posibles causas de error sucedió. Los programadores evitan las RUP en los mensajes de error.

No copie los mensajes de error en diferentes lugares del código. Si un usuario ve el mensaje en su programa y envía comentarios, un caso más afortunado es cuando puede comprender lo que significa su mensaje de error. El caso menos afortunado es que al menos puede grep todo el código fuente y encontrar el lugar donde el programa se colgó. Si encuentra el mismo mensaje en varios lugares, no puede ayudarse a sí mismo.

Ah, y no olvide mencionar las posibles consecuencias: "El Sistema de Prevención de Ardilla dejó de funcionar. Cualquier cosa almacenada en sus discos duros puede ser modificada aleatoriamente por las ardillas". "El Sistema de Prevención de Ardilla dejó de funcionar. En su lugar, las Ardillas serán prevenidas por el Marco General de Prevención". Hay una diferencia en la severidad.

Un buen mensaje de error tiene tres partes:

El problema : explica que ha ocurrido un error;
La causa : explica qué causó el problema;
La solución : explica cómo superar el problema.

Si está escribiendo o revisando su mensaje de error, primero concéntrese en obtener estos tres puntos. Incluso si el mensaje es muy largo, no te preocupes por eso cuando escribas por primera vez. Siempre puede regresar y simplificarlo más tarde.

Pero lo opuesto no es verdad. Es difícil dar forma a un mensaje pequeño en uno que explique claramente el problema, la causa y la solución del problema. Estará editando constantemente sus pensamientos para asegurarse de que el mensaje se quede pequeño, y en algún momento se bloqueará. Sí, he experimentado ese problema varias veces, por lo que sé lo difícil que se siente.

Después de asegurarse de que su mensaje contenga todas estas tres partes, es hora de revisarlo. Debe editarlo para asegurarse de que:

¿Está centrado el usuario ? Evite la jerga y las palabras que su audiencia tendrá dificultades para entender;
Es directo - como dijo William Strunk, "Ponga declaraciones en forma positiva. Evite lenguaje domesticado, incoloro, vacilante y no comprometido ";
Omite palabras innecesarias : cortar, cortar, cortar.

Como puede ver, este marco es simple y no necesita mucha reflexión.

Fuentes: