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.