Est-ce une mauvaise pratique d'ajouter des liens externes dans la documentation?

9

Souvent, je me retrouve à résoudre des bugs en trouvant la réponse sur Stack Overflow. Est-ce une mauvaise pratique d'ajouter un extrait de la raison pour laquelle j'ai fait ce que j'ai fait, puis d'ajouter un lien vers un article ou une page sur le Web?

documentation TruthOf42
la source
Duplication possible de Dois-je ajouter des notes MSDN ou des liens Stack Overflow au code source?
moucher
FWIW Je le fais tout le temps, et j'ai même demandé comment le faire correctement sur StackExchange . Non pas que cela réponde à votre question, mais certains arguments pour et contre peuvent être trouvés là-bas.
4
Copie possible de Est-il OK de mettre un lien vers des sites de questions / réponses dans les commentaires d'un programme?
Doc Brown
Est la question uniquement sur les liens (OK pour moi), car vous mentionnez également la copie de parties du code / réponse. C'est quelque chose que je ne ferais que pour expliquer un algorithme ou un traitement complexe. La structure et la dénomination du code doivent être claires indépendamment de l'endroit où vous lisez une solution.
Kwebble

Réponses:

14

Je ne pense pas que ce soit mauvais, mais les liens externes ont la mauvaise habitude de disparaître au cours du cycle de vie d'une solution. Ce faisant, je recommande de mettre un résumé suffisant qui aidera le lecteur si le lien n'est plus fonctionnel.

Jim Rush
la source
3
L'ajout d'un résumé utile pour deux raisons: 1) Comme Jim l'a souligné, cela aide le lecteur à comprendre si le lien est obsolète ou non, et 2) il oblige le développeur à copier le code à partir du lien pour comprendre ce qu'il copie. Cela permet de s'assurer que le code n'est pas uniquement utilisé car «il résout le problème».
Mage Xy
7

C'est pourquoi les entreprises devraient avoir leur propre référentiel de connaissances. Par exemple, mon entreprise possède une Redmine corporative qui est utilisée pour la gestion de projet, la billetterie (suivi des bogues et des tâches) et l'outil que j'utilise le plus, un wiki . Toutes ces fonctionnalités par projet :-)

Qu'avons-nous sur le wiki du projet?

  • Liens vers la documentation: fonctionnel, technique, architecture, exigences.
  • Acteurs impliqués: Chef de Projet, Devs, Responsables Grands Comptes Clients, ...
  • Description par environnement: Machines virtuelles, OS, serveurs, configurations ...
  • Divers: Toute chose importante / intéressante (liée au projet) apprise au cours de la vie du projet.
  • Encore quelques pages.

J'ai mis la bibliographie (liens) sur Misc wiki. Mais seulement de ceux en qui j'ai confiance:

  • Débordement de pile : votes positifs et bien argumentés
  • Génie logiciel Stackexchange : votes positifs et bien argumentés
  • MKyong.com : J'aime cette page. C'est vraiment utile et ses tutoriels sont vraiment faciles à suivre
  • MDN
  • W3C.org
  • W3Schools : Sa documentation est interactive (la plupart des cas) et conviviale.
  • OWASP : pour référencer les problèmes liés à la sécurité et aux vulnérabilités
  • Pages Web officielles: Parfois, les meilleurs tutoriels ou explications se trouvent sur les pages Web officielles.

Ma bibliographie est accompagnée d'un résumé tapé par mes soins, afin de m'assurer d'avoir bien compris à quoi je fais un lien. J'essaie de garder Javadoc aussi clair que possible. Chaque lien dans le code fait référence au wiki de Redmine ou au code de problème de Redmine.

En l'absence d'outils comme Redmine, j'ai trouvé que les fichiers Markdown étaient utiles à ces fins. Dans l'ensemble, les développeurs en raison de ces fichiers sont dans le SCM et accompagnent le code.

Laiv
la source
1
Je suis d'accord avec tout sauf en faisant confiance à W3Schools.com. Vous pouvez trouver la plupart de ce qui se trouve sur MDN qui a beaucoup plus d'autorité.
Alternatex
1
W3schools existe depuis plus longtemps que MDN. Je peux me tromper, mais je pense que W3schools a plus de contenu, de tutoriels et de documentation sur les technologies Web. Malgré ses problèmes, il reste l'une des meilleures références pour les débutants car son contenu est beaucoup plus convivial et interactif. Du côté positif, MDN a une grande communauté qui soutient son contenu. Mais à la baisse, il ne pourrait jamais être impartial dans sa documentation car il a un navigateur à défendre. Quoi qu'il en soit, je suis d'accord avec vous, maintenant un jour, MDN semble avoir plus d'autorité. si cela ne vous dérange pas, j'ajouterai la référence à ma réponse.
Laiv
4

Les liens vers le Web sont quelque peu problématiques en tant que documentation, car Internet ne garantit pas que le contenu que vous voyez derrière eux sera le même que celui d'un futur lecteur de documents. Si possible, efforcez-vous de ne vous lier qu'aux ressources qui sont très peu susceptibles de changer.

Par exemple, lorsque vous créez un lien vers Wikipedia, vous devez créer un lien explicite vers la version actuelle plutôt que le nom générique de l'article. Pour stackexchange.com, eh bien, il semble peu probable que cela disparaisse pour le moment, mais les questions sont éditées ou même supprimées tout le temps, et dans cinq ans, un nouveau point de rassemblement pourrait avoir vu le jour. Je ne risquerais pas de suspendre de la documentation qui présente une valeur commerciale substantielle sur un site si externe à votre organisation.

Kilian Foth
la source
"Wayback Machine - Internet Archive" (web.archive.org/) est un bon endroit pour vérifier le contenu supprimé.
Kromster