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
Réponses:
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.
la source
Oui le plus définitivement MAIS:
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.
la source
Vous devriez préférer pointer vers la documentation hors ligne fournie avec la bibliothèque, plutôt qu'en ligne.
(é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 quehttps
. Ou nous pourrions tous revenir augopher
protocole.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).
la source
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?
la source