¿Incluye un enlace a la documentación relevante en el mensaje de error?

Creamos una biblioteca comercial y ejemplos de código que están siendo utilizados por desarrolladores externos. Tenemos documentación (cerrada, disponible para usuarios registrados) que explica ampliamente cómo usar la biblioteca.

Muchos de los desarrolladores son usuarios nuevos, por lo que se encuentran muchos errores rudimentarios.

¿Es apropiado incluir enlaces a la documentación en el registro de errores? ¿Cuáles son los posibles inconvenientes? Puedo prever algunos, pero parece posible superar lo siguiente

• URL de documentación desactualizada
• Errores específicos de la versión que no se reflejan en la última documentación
• Algo más está mal, y estamos perdiendo el tiempo del desarrollador enviándolo a un documento irrelevante

Debajo de un ejemplo de lo que quiero decir, ¿es una buena idea agregar el texto en negrita?

[ERROR] Error al ejecutar el objetivo org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: generate (default-cli) on project standalone-pom: El arquetipo deseado no existe (com.example.library. arquetipos: library-archetype-blank: 1.2.3.0) -> Consulte http://example.com/docs/setting-up-an-archetype para obtener más información y una posible solución de problemas

De acuerdo con estas pautas de mensajes de error , y mi experiencia, a las personas les gusta ahorrar tiempo al no leer la documentación o la ayuda. Buscar en Google un error también puede estar más allá de ellos, así que incluya un enlace cuando tengan una razón para hacer clic en él.

Finalmente, probablemente ya conozca la Primera Ley de Documentación Informática de Nielsen: la gente no la lee. Este hallazgo es aún más fuerte para los sitios web, donde los usuarios realmente evitan cualquier lectura que no sea esencial para su tarea. Haga clic en Ayuda Nunca.

Los usuarios leen la documentación del sistema solo cuando están en problemas (esa es la Segunda Ley). Están particularmente atentos cuando quieren recuperarse de un error. Dado esto, puede usar mensajes de error como un recurso educativo para impartir una pequeña cantidad de conocimiento a los usuarios. Por supuesto, los mensajes de error deben ser breves y precisos, al igual que todo el contenido web. Sin embargo, los mensajes de error aún pueden enseñar a los usuarios un poco sobre cómo funciona el sistema y darles la información que necesitan para usarlo mejor. Para promover ese fin, la tecnología subyacente de la Web hace posible otra directriz:

Los enlaces de hipertexto se pueden usar para conectar un mensaje de error conciso a una página con material de antecedentes adicional o una explicación del problema. (Sin embargo, no exagere).

Sí más definitivamente PERO:

• La podredumbre del enlace será un problema. Lo ideal sería generar el enlace dinámicamente a partir de un documento de destino conocido, pero obtener el prefijo de alguna forma de configuración. Si el servidor cambia, puede mantener válido el código anterior actualizando este elemento de configuración. También puede hacer que el documento esté disponible localmente simplemente cambiando esta configuración de prefijo.
• Control de versiones : con el mismo espíritu, si puede incluir el control de versiones en el enlace de alguna manera para que el enlace siempre apunte a la versión correcta de la documentación.
• Hacer que el documento sea editable Algo así como un sitio de tipo wiki para su documentación donde puede corregir dinámicamente los errores, idealmente también permite a los usuarios comentar directamente en la página. esto hará que sea mucho más fácil para sus usuarios participar y encontrar lo que necesitan y obtendrá información de oro para mantener su documento en buenas condiciones de trabajo, pero asegúrese de monitorearlo regularmente y, sobre todo, participar activamente.
• Las plantillas generadas hacen que su sistema de compilación genere la plantilla básica para la documentación a partir de anotaciones en el código directamente. Sin embargo, manténgalo simple, pero esto garantizará que todos los enlaces siempre apunten a una documentación válida. Si usa un wiki, asegúrese de poder empujar estas plantillas fácilmente, y asegúrese de que puede promocionar el sitio de documentación de la misma manera que lo hace para su código (tenga un sitio de desarrollo que sea diferente del sitio de producción y promocione el código a la producción). realice las inserciones en el sitio de producción automáticamente).

Si desarrolla con Java o .NET, el documento podría incluirse en un archivo jar o un archivo DLL y, al cambiar el prefijo, su código podría buscarlo localmente.

Si eliges el enfoque wiki, recomiendo encarecidamente DokuWiki por su simplicidad y por el hecho de que se basa en archivos de texto plano que lo harían muy amigable para la inyección automatizada desde el sistema de compilación. Dicho esto, no sé lo suficiente sobre su entorno o clientes para saber realmente si esto sería una buena opción para YMMV.

Algunas de las herramientas más exitosas que he creado adoptaron un enfoque similar en el que el mensaje de error estaba dirigido al usuario real que probablemente realizaría la tarea. Eso significaba que tenía que hacer MUCHA captura y ajuste de excepciones para asegurarme de que el error estuviera en el nivel apropiado de abstracción. También me aseguré de que cada mensaje de error incluiría las fuentes más probables de errores y señala posibles soluciones "¿Olvidó establecer el valor de configuración xxxx?", "Asegúrese de que xxx e yyy no entren en conflicto dándoles nombres diferentes", etc. Donde XXX y demás se generarían a partir del contexto donde ocurrió el error.

Este enfoque fue algo más simple pero también más limitado. Sin embargo, tenía la ventaja de que la documentación siempre estaría presente cuando fuera necesario, sin que se pudriera el enlace.

Su enfoque es la próxima evolución. Mucho más complejo pero también tiene muchos más rendimientos potenciales. Sin embargo, será costoso, pero si se hace correctamente, se amortizará fácilmente.

Debe preferir señalar la documentación fuera de línea incluida con la biblioteca, en lugar de en línea.

(com.example.library.archetypes: library-archetype-blank: 1.2.3.0) -> Consulte /usr/share/myprog-3.8.1/docs/setting-up-an-archetype para obtener más información y una posible solución de problemas

(obviamente, si se trata de una biblioteca de Windows, la ruta sería diferente).

Los beneficios aquí son:

• De esta manera, la documentación siempre está sincronizada con la biblioteca. Las personas desarrollan y solucionan problemas de versiones antiguas de bibliotecas. Y su empresa puede cambiar su nombre, cambiar el nombre del producto, o alguien puede dejar caer la pelota en la renovación example.com.

• La web cambia rápidamente. El enlace que proporciona es http, pero en unos años sus principales navegadores solo serán compatibles https. O todos podríamos volver al gopherprotocolo.

• La solución de problemas de la aplicación no siempre ocurre en un entorno con acceso a Internet (o al menos acceso directo a su dominio).

• Usted menciona que su documentación está detrás de un muro de "autenticación". Tener que crear una cuenta en un sitio web solo para entender un mensaje de error no es agradable (es por eso que SO no requiere que las personas inicien sesión).

Hay una forma realmente exitosa de abordar este problema. Asegúrese de que la excepción combinada con el mensaje sea lo suficientemente única como para que pegarlos en una búsqueda en la web pueda encontrar fácilmente todas las publicaciones relevantes sobre exactamente este problema.

Esta es la razón secreta por la que odio tanto las excepciones de puntero nulo. Claro que odio que incluso tengamos que buscar nulos, pero lo que más me molesta es que, cuando me encuentro con uno, el único identificador verdaderamente único en el que tengo que buscar es un número de línea volátil.

Sí, me gustaría poder buscarlos. Oh, claro, sé que sucedió porque algo se dejó nulo y luego se usó. Sin embargo, lo que no siempre es obvio de inmediato es POR QUÉ algo se dejó nulo.

Tan seguro, considere todas estas otras soluciones de documentación. Pero lo más perezoso que puedes hacer que me hará más bien es darme algo que pueda googlear.

¿Bastante por favor?