Inclure un lien vers la documentation pertinente dans le message d'erreur?

Nous créons une bibliothèque commerciale et des exemples de code qui sont utilisés par des développeurs externes. Nous avons une documentation (fermée, disponible pour les utilisateurs enregistrés) qui explique en détail comment utiliser la bibliothèque.

Beaucoup de développeurs sont de nouveaux utilisateurs, donc beaucoup d'erreurs rudimentaires sont rencontrées.

Est-il approprié d'inclure des liens vers la documentation dans le journal des erreurs? Quels sont les inconvénients possibles? Je peux en prévoir quelques-uns, mais il semble possible de surmonter les problèmes suivants

• URL de la documentation obsolète
• Erreurs spécifiques à la version qui ne sont pas reflétées dans la dernière documentation
• Quelque chose d'autre ne va pas, et nous perdons le temps du développeur en l'envoyant vers un document non pertinent

Ci-dessous un exemple de ce que je veux dire, est-ce une bonne idée d'ajouter le texte en gras?

[ERREUR] Échec de l'exécution de l'objectif org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: générer (default-cli) sur le projet standalone-pom: l'archétype souhaité n'existe pas (com.example.library. archétypes: bibliothèque-archétype-vide: 1.2.3.0) -> Veuillez consulter http://example.com/docs/setting-up-an-archetype pour plus d'informations et un éventuel dépannage

Selon ces directives de message d'erreur et mon expérience, les gens aiment gagner du temps en ne lisant pas la documentation ou l'aide. La recherche d'une erreur sur Google peut également les dépasser, alors incluez un lien lorsqu'ils ont une raison de cliquer dessus.

Enfin, vous connaissez probablement déjà la première loi de Nielsen sur la documentation informatique: les gens ne la lisent pas. Cette constatation est encore plus forte pour les sites Web, où les utilisateurs évitent vraiment toute lecture qui n'est pas essentielle à leur tâche. Cliquez sur Aide? Jamais.

Les utilisateurs ne lisent la documentation du système qu'en cas de problème (c'est la deuxième loi). Ils sont particulièrement attentifs lorsqu'ils souhaitent se remettre d'une erreur. Compte tenu de cela, vous pouvez utiliser des messages d'erreur comme ressource pédagogique pour transmettre une petite quantité de connaissances aux utilisateurs. Bien sûr, les messages d'erreur doivent être brefs et précis, tout comme tout le contenu Web. Cependant, les messages d'erreur peuvent tout de même enseigner aux utilisateurs comment le système fonctionne et leur fournir les informations dont ils ont besoin pour mieux l'utiliser. À cette fin, la technologie sous-jacente du Web permet une autre ligne directrice:

Des liens hypertextes peuvent être utilisés pour connecter un message d'erreur concis à une page contenant des informations supplémentaires ou une explication du problème. (N'en faites pas trop, cependant.)

Oui le plus définitivement MAIS:

• La pourriture des liens va être un problème. Idéalement, générez le lien dynamiquement à partir d'un document cible connu mais obtenez le préfixe d'une forme de configuration. Si le serveur change, vous pouvez conserver l'ancien code valide en mettant à jour cet élément de configuration. Vous pouvez également rendre le document disponible localement en changeant simplement cette configuration de préfixe.
• Gestion des versions : dans le même esprit, si vous pouvez inclure la gestion des versions dans le lien à un certain titre afin que le lien pointe toujours vers la version correcte de la documentation.
• Rendre le document modifiable Quelque chose comme un site de type wiki pour votre documentation où vous pouvez corriger dynamiquement les erreurs, idéalement aussi permettre aux utilisateurs de commenter directement sur la page. cela permettra à vos utilisateurs de participer et de trouver ce dont ils ont besoin beaucoup plus facilement et vous obtiendrez des informations de base pour garder votre doc en bon état de fonctionnement, mais assurez-vous de le surveiller régulièrement et surtout de participer activement vous-même.
• Les modèles générés permettent à votre système de génération de générer directement le modèle de base pour la documentation à partir des annotations dans le code. Restez simple, mais cela garantira que chaque lien pointe toujours vers une documentation valide. Si vous utilisez un wiki, assurez-vous que vous pouvez pousser ces modèles facilement et assurez-vous que vous pouvez promouvoir le site de documentation de la même manière que pour votre code (avoir un site de développement différent du site de production et promouvoir le code en prod volonté effectuer les insertions dans le site de production automatiquement).

Si vous développez avec Java ou .NET, la doc peut être incluse dans un fichier jar ou un fichier DLL et en modifiant le préfixe, votre code peut le récupérer localement à la place.

Si vous choisissez l'approche wiki, je recommande chaudement DokuWiki pour sa simplicité et pour le fait qu'il est basé sur des fichiers texte plats qui le rendraient très convivial pour l'injection automatisée à partir du système de construction. Cela dit, je ne connais pas suffisamment votre environnement ou vos clients pour vraiment savoir si ce serait un bon ajustement YMMV.

Certains des outils les plus efficaces que j'ai créés ont adopté une approche similaire dans laquelle le message d'erreur était destiné à l'utilisateur réel qui effectuerait probablement la tâche. Cela signifiait que je devais faire BEAUCOUP de capture et d'encapsulation d'exceptions pour m'assurer que l'erreur était au niveau d'abstraction approprié. J'ai également veillé à ce que chaque message d'erreur inclue les sources d'erreurs les plus probables et pointe vers des solutions potentielles "Avez-vous oublié de définir la valeur de configuration xxxx?", "Assurez-vous que xxx et yyy n'entrent pas en conflit en leur donnant des noms différents", etc. Où XXX et ainsi de suite seraient générés à partir du contexte où l'erreur s'est produite.

Cette approche était quelque peu plus simple mais aussi plus limitée. Il avait cependant l'avantage que la documentation serait toujours présente en cas de besoin, aucune pourriture de lien possible.

Votre approche est la prochaine évolution. Beaucoup plus complexe, mais a également des rendements potentiels beaucoup plus. Cela coûtera cher, mais s'il est bien fait, il sera facilement rentable.

Vous devriez préférer pointer vers la documentation hors ligne fournie avec la bibliothèque, plutôt qu'en ligne.

(com.example.library.archetypes: library-archetype-blank: 1.2.3.0) -> Veuillez voir /usr/share/myprog-3.8.1/docs/setting-up-an-archetype pour plus d'informations et un éventuel dépannage

(évidemment si c'est une bibliothèque Windows, le chemin serait différent).

Les avantages ici sont:

• De cette façon, la documentation est toujours synchronisée avec la bibliothèque. Les gens développent et résolvent les anciennes versions de bibliothèque. Et votre entreprise peut changer son nom, changer le nom du produit, ou quelqu'un peut laisser tomber la balle lors du renouvellement example.com.

• Le Web change rapidement. Le lien que vous donnez est http, mais dans quelques années, ses principaux navigateurs probables ne prendront en charge que https. Ou nous pourrions tous revenir au gopherprotocole.

• Le dépannage des applications ne se produit pas toujours dans un environnement avec accès à Internet (ou au moins un accès direct à votre domaine).

• Vous mentionnez que votre documentation se trouve derrière un mur "d'authentification". Devoir créer un compte sur un site Web juste pour comprendre un message d'erreur n'est pas agréable (c'est pourquoi SO n'exige pas que les gens se connectent).

Il existe un moyen très efficace d'aborder ce problème. Assurez-vous que l'exception associée au message est suffisamment unique pour que leur collage dans une recherche sur le Web puisse facilement trouver toutes les publications pertinentes sur exactement ce problème.

C'est la raison secrète pour laquelle je déteste tellement les exceptions de pointeur nul. Bien sûr, je déteste que nous devions même vérifier la valeur null, mais ce qui me dérange le plus, c'est que, lorsque j'en rencontre un, le seul identifiant vraiment unique sur lequel je dois rechercher est un numéro de ligne volatile.

Oui, j'aimerais pouvoir les rechercher. Oh bien sûr, je sais que c'est arrivé parce que quelque chose a été laissé nul et utilisé. Ce qui n'est pas toujours immédiatement évident, c'est POURQUOI quelque chose a été laissé nul.

Alors bien sûr, considérez toutes ces autres solutions de documentation. Mais la chose la plus paresseuse que vous pouvez faire qui me fera le plus de bien est de me donner quelque chose que je peux google.

Jolie s'il-vous-plaît?