¿Es una mala práctica agregar enlaces externos en la documentación?

9

A menudo me encuentro resolviendo errores al encontrar la respuesta en Stack Overflow. ¿Es una mala práctica agregar un fragmento de por qué hice lo que hice y luego agregar un enlace a un artículo o página de la web?

documentation TruthOf42
fuente
Posible duplicado de ¿Debo agregar notas de MSDN o enlaces de desbordamiento de pila al código fuente?
mosquito
FWIW Lo hago todo el tiempo, e incluso pregunté cómo hacerlo correctamente en StackExchange . No es que responda su pregunta, pero algunos argumentos a favor y en contra se pueden encontrar allí.
44
Posible duplicado de ¿Está bien poner un enlace a sitios de preguntas y respuestas en los comentarios de un programa?
Doc Brown
Es la pregunta solo sobre los enlaces (está bien para mí), porque también mencionas copiar partes del código / respuesta. Esto es algo que solo haría para explicar un algoritmo o procesamiento complejo. La estructura del código y los nombres deben ser claros independientemente de dónde lea sobre una solución.
Kwebble

Respuestas:

14

No creo que sea malo, pero los enlaces externos tienen la mala costumbre de desaparecer durante el ciclo de vida de una solución. Al hacerlo, recomiendo poner un resumen suficiente que ayudará al lector si el enlace ya no funciona.

Jim Rush
fuente
3
Agregar un resumen útil por dos razones: 1) Como señaló Jim, ayuda al lector a comprender si el enlace está desactualizado o no, y 2) obliga al desarrollador a copiar el código del enlace para comprender lo que están copiando. Esto ayuda a garantizar que el código no solo se use porque "soluciona el problema".
Mage Xy
7

Es por eso que las empresas deberían tener su propio repositorio de conocimiento. Por ejemplo, mi empresa tiene una Redmine corporativa que se utiliza para la gestión de proyectos, la emisión de tickets (seguimiento de errores y tareas) y la herramienta que más uso, un wiki . Todas estas características por proyecto :-)

¿Qué tenemos en la wiki del proyecto?

  • Enlaces a documentación: funcional, técnica, arquitectura, requisitos.
  • Actores involucrados: Gerente de proyecto, Desarrolladores, Gerentes de cuentas clave del cliente, ...
  • Descripción por entorno: máquinas virtuales, SO, servidores, configuraciones ...
  • Otra información: Cualquier cosa importante / interesante (relacionada con el proyecto) aprendida durante la vida del proyecto.
  • Algunas páginas más.

Puse bibliografía (enlaces) en la wiki de Misc . Pero solo de aquellos en quienes confío:

  • Desbordamiento de pila : votos positivos y bien discutidos
  • Software Engineering Stackexchange : votos positivos y bien discutidos
  • MKyong.com : me gusta esta página. Es realmente útil y sus tutoriales son realmente fáciles de seguir.
  • MDN
  • W3C.org
  • W3Schools : su documentación es interactiva (la mayoría de los casos) y fácil de usar.
  • OWASP : para hacer referencia a problemas relacionados con la seguridad y las vulnerabilidades
  • Páginas web oficiales: a veces los mejores tutoriales o explicaciones se encuentran en las páginas web oficiales.

Mi bibliografía viene con un resumen escrito por mí, para asegurarme de que he entendido a qué me estoy vinculando. Intento mantener Javadoc lo más claro posible. Cada enlace en el código hace referencia a la wiki de Redmine o al código de problema de Redmine.

En ausencia de herramientas como Redmine, descubrí que los archivos Markdown son útiles para estos fines. En general, los desarrolladores debido a estos archivos están en el SCM y viene junto con el código.

Laiv
fuente
1
Estoy de acuerdo con todo excepto confiar en W3Schools.com. Puede encontrar la mayor parte de lo que hay en MDN, que tiene mucha más autoridad.
Alternatex
1
W3schools ha existido por más tiempo que MDN. Puedo estar equivocado, pero creo que W3schools tiene más contenido, tutoriales y documentación sobre tecnologías web. A pesar de sus problemas, sigue siendo una de las mejores referencias para principiantes porque su contenido es mucho más fácil de usar e interactivo. En el lado positivo, MDN tiene una gran comunidad que respalda su contenido. Pero en el lado negativo, nunca podría ser imparcial en su documentación porque tiene un navegador para defender. De todos modos, estoy de acuerdo con usted, hoy en día MDN parece tener más autoridad. Si no le importa, agregaré la referencia a mi respuesta.
Laiv
4

Los enlaces a la web son algo problemáticos como documentación porque Internet no garantiza que el contenido que está viendo detrás de ellos sea el mismo que verá un futuro lector de documentos. Si es posible, trate de vincular solo a los recursos que es muy poco probable que cambien.

Por ejemplo, cuando se vincula a Wikipedia, debe vincular explícitamente a la versión de hoy en lugar del nombre genérico del artículo. Para stackexchange.com, bueno, en este momento parece poco probable que desaparezca, pero las preguntas se editan o incluso se eliminan todo el tiempo, y dentro de cinco años podría haber surgido un nuevo punto de encuentro. No me arriesgaría a colgar documentación que tenga un valor comercial sustancial en un sitio tan externo a su organización.

Kilian Foth
fuente
"Wayback Machine - Internet Archive" (web.archive.org/) es un buen lugar para verificar el contenido eliminado.
Kromster