¿Por qué citar las ID de errores en las notas del parche puede considerarse una mala práctica?

28

Basado en un comentario y votos posteriores de Bug reopen vs. new :

Citar ID de errores en las notas del parche es simplemente ... muy hostil. - Krelp

Parece que al menos algunas personas sienten que hacer referencia a ID de errores en las notas del parche no es una buena idea. Soy un desarrollador bastante inexperto, así que me pregunto por qué ese es el caso.

Travis Northcutt
fuente
27
no citar ID de errores en las notas del parche es simplemente ... muy poco profesional. Tipo de basura todo el punto de tener un rastreador de problemas
mosquito
La misma razón por la que publicar solo enlaces como respuestas de StackExchange está mal visto: si solo publica un enlace, en SE eso es malo porque (1) requiere seguir para obtener una explicación y (2) puede volverse inválido en el futuro si el el enlace muere o el contenido cambia. Del mismo modo, poner solo ID de errores en las notas del parche (1) requiere ir al rastreador de errores para obtener una explicación y (2) puede volverse inválido en el futuro si cambia el sistema del rastreador de errores. Incluir un enlace en una respuesta SE o un ID de error en una nota de parche está bien (y en realidad es una buena práctica) como una adición a una explicación regular.
Ben Lee

Respuestas:

51

En mi opinión, es una buena práctica, suponiendo que sus usuarios tengan acceso de lectura a su base de datos de errores. Hay muchas ocasiones en que las personas esperan que se solucione un determinado error para decidir cuándo actualizar.

Creo que lo que está mal visto es solo citar la identificación del error y nada más. Siempre debe proporcionar una descripción que sea comprensible sin ir al rastreador de errores. Eso también le permite cambiar los rastreadores de errores en el futuro sin invalidar por completo sus notas de lanzamiento anteriores.

Karl Bielefeldt
fuente
Puede citar a través de un resolutor de referencia abstracta, también conocido como redireccionamiento de URL.
Donal Fellows
Como usted dice, la sección "Errores solucionados" (o similares) debe incluir el Id y el título para que el lector no tenga que buscar el error para comprender exactamente qué está incluido y qué no.
StuperUser
55
@StuperUser: ID y título, como mínimo .
Oded
Lo molesto es encontrar anotaciones de ID de error solo en los comentarios cuando el sistema de ID de requisito / error referenciado ya no está en uso.
jfrankcarr
14

Es, como se dijo en el comentario citado ... hostil.

Antipático contigo mismo

Imagine el siguiente escenario. Estás viendo los registros en el control de código fuente. Te preguntas qué cambió un commit. En lugar de explicarlo en inglés simple, te dice:

Resuelto # 1307

Ejecutas el sistema de seguimiento de errores, esperando tener algo útil. El error # 1307 se informa como resuelto. En la descripción, ves:

El mismo error que # 1284

Gracias, es muy útil. Ahora tiene que navegar al informe de errores # 1284 para leer que es un duplicado del error # 1113 que se refiere a los errores # 1112, # 1065 y # 1067.

Cinco minutos después, no tienes idea de lo que estás buscando al principio.

Un mensaje de registro de control de versiones mucho más útil sería:

Se resolvió un problema con los usuarios que no podían iniciar sesión con una contraseña de más de 25 caracteres (ver # 1307), eliminando la aplicación de la misma política de longitud de contraseña a la capa de acceso a datos que la utilizada en el sitio web.

De la misma manera, en el sistema de seguimiento de errores, el informe # 1307 podría explicarse por sí solo , recordando de qué se trataba el informe de errores # 1284 y cómo el nuevo es diferente del anterior.

Antipático con los clientes

Este no es el único problema de amistad.

Una segunda es que al hacer demasiada referencia sin información adicional, está haciendo que las notas del parche / registros de control de versiones / informes del sistema de seguimiento de errores no puedan utilizarse para alguien que no esté muy familiarizado con esos sistemas . Cuando maneja diariamente un sistema de seguimiento de errores, sabe cómo navegar rápidamente por los informes, ver varios informes uno al lado del otro, etc. Cuando es un cliente sin antecedentes técnicos, puede perderse fácilmente.

Aquí nuevamente, los mensajes más detallados son muy útiles que solo una referencia. Tenga en cuenta que aún desea mantener referencias: nada está más mal que un error que es el mismo que encontró hace dos semanas, pero no recuerde su ID.


Como nota, el mismo problema existe en muchas jurisdicciones. En Francia, por ejemplo, no es inusual que una legislación haga referencia a múltiples fuentes, que pueden cambiar mientras tanto. Esto significa que para entenderlo completamente, debe pasar algunas veces horas en una biblioteca, buscando docenas de textos referidos, cada texto con sus propias referencias a otros.

Arseni Mourzenko
fuente
55
Esto no es un problema con el documento de lanzamiento; Esto es un problema con el nivel de detalle en los errores. Un título debe describir el problema real y el cuerpo de cada error tiene Resultado esperado y Resultado real. ¿No deberían cerrarse los errores como ha descrito como duplicados?
StuperUser
Basado en tu edición. Has citado el Id en tu mensaje mucho más útil. ¿Quiso decir en su comentario original que citar SOLO los ID sin más información no es útil, mientras que una explicación adecuada Y el ID es útil?
StuperUser
1
@StuperUser: exactamente. Proporcionar una explicación ayuda a las personas que solo quieren saber de qué se trata el registro de confirmación / nota de parche / informe de error, sin pasar diez minutos leyendo el contenido referenciado. Todavía se requieren identificaciones para el seguimiento y las personas que necesitan información muy detallada, precisa y completa.
Arseni Mourzenko
2

No hay nada de malo en citar números de problemas en las notas del parche, siempre que los usuarios puedan leer el problema que se cita. Si su base de datos de errores permite que alguien lea, citar el número de error puede ser muy útil. (Una mejor opción, si las notas de su parche están en un formato que permite enlaces, haga que esas ID de problemas sean enlaces al problema en cuestión). Esto no significa que deba exponer todos los problemas al público en general; aún puede ser útil tener unos que estén envueltos (por ejemplo, ¡dónde tienen contraseñas activas!)

Citar un número de problema donde la persona que lee no puede ir y buscar los detalles y el historial del error, eso es bastante hostil. No es que citar tales problemas sin la identificación del problema sea mucho más amigable.

Compañeros de Donal
fuente
"donde la persona que lee no puede ir y buscar los detalles" como alguien que ha sido esa persona , no lo llamaría realmente hostil. Utilicé el ID de problema para comunicarme con el equipo de soporte / desarrollo que a su vez tenía acceso al rastreador de problemas. El hecho de que fuera invisible para mí personalmente era simplemente una molestia menor
mosquito
2

Obviamente depende de quiénes son las personas que leerán las notas del parche y los usuarios objetivo del software.

Pero en la mayoría de los casos, a la gran mayoría de sus usuarios simplemente no les importa cuál es la identificación del error. No les importa por qué se rompió, cuál es la solución o cualquier otra cosa; solo quieren saber qué cambió con una descripción textual muy sucinta sin tener que ir a otra página para cada cambio.

Citar las ID de errores me hace parar y pensar, y yo, como usuario, no quiero pensar. Es una especie de problema de usabilidad.

Echar un vistazo, por ejemplo, en el registro de cambios de Visual Assist X . Todas esas ID de error vinculadas son solo ruido que me distrae de comprender lo que cambió. Y este es un complemento para un Visual Studio, dirigido a programadores. Y yo soy programador. Si esto me molesta, imagine al usuario promedio que ni siquiera sabe qué es un rastreador de errores ...

PD: fui el autor del comentario que generó la pregunta

Thomas Bonini
fuente
1
Sinceramente, encuentro útil la documentación al final de ese enlace. Comienza con un resumen y luego me dirige a los detalles. Microsoft a menudo hace una vinculación similar en los artículos de KB, no es que hacerlo lo haga una buena práctica, pero ciertamente está muy extendido y aparentemente proporciona valor a muchos usuarios.
Joshua Drake
1

Una identificación de error es obligatoria para un punto de referencia . Las razones:

  • Evite la ambigüedad: dos o más errores pueden tener descripciones similares. Entonces uno necesitaría un poco de ancla para distinguir entre ellos.
  • Comodidad : cuando se habla de un error, ya sea con un cliente o internamente, la identificación del error a menudo se usa como una forma breve. Si se omite la ID de las notas del parche, será difícil discutir sobre ellas:

3052 ya estaba arreglado, todavía trabajando en 3077

es más conveniente que:

Se solucionó el "bloqueo de la aplicación al aplicar el botón", que seguía funcionando en la "NullReferenceException al hacer clic en cambiar usuario"

KMoraz
fuente
(1) ¿Qué le impide combinarlo, como lo sugiere MainMa? (2) ¿Por qué cometes errores solucionados? ¿Por qué no se compromete después de que 3052 se haya solucionado, incluso antes de comenzar a trabajar en 3077?
JensG
0

Diría que depende de su sistema: tengo suerte de que el que uso detecte automáticamente tales referencias en los mensajes de confirmación y agregue un enlace al ticket almacenado en el rastreador de errores, por lo que no es un problema.

Pero si estuviera en un sistema donde no está disponible, aún mencionaría el ID del ticket (de esa manera, puede buscar rápidamente en los registros por ID del ticket ) junto con una breve descripción de qué es el error.

picos salvajes
fuente