É uma má prática adicionar links externos na documentação?

9

Muitas vezes, me pego resolvendo bugs encontrando a resposta no Stack Overflow. É uma má prática adicionar um trecho do motivo pelo qual fiz o que fiz e depois adicionar um link a um artigo ou página da Web?

documentation TruthOf42
fonte
Possível duplicata de Devo adicionar notas do MSDN ou links de estouro de pilha ao código-fonte?
mosquito
FWIW Eu faço isso o tempo todo e até perguntei como fazer isso corretamente no StackExchange . Não que ele responda à sua pergunta, mas alguns argumentos a favor e contra podem ser encontrados por lá.
4
Possível duplicata de Posso colocar um link para sites de perguntas e respostas nos comentários de um programa?
Doc Brown
É a pergunta apenas sobre os links (OK para mim), porque você também menciona copiar partes do código / resposta. Isso é algo que eu faria apenas para explicar um algoritmo ou processamento complexo. A estrutura do código e a nomeação devem ser claras, independentemente de onde você lê sobre uma solução.
Kwebble

Respostas:

14

Não acho ruim, mas os links externos têm o mau hábito de desaparecer durante o ciclo de vida de uma solução. Ao fazer isso, recomendo colocar um resumo suficiente que ajude o leitor se o link não estiver mais funcional.

Jim Rush
fonte
3
Adicionar um resumo útil por duas razões: 1) Como Jim apontou, ajuda o leitor a entender se o link está desatualizado ou não e 2) força o desenvolvedor a copiar o código do link para entender o que está copiando. Isso ajuda a garantir que o código não esteja sendo usado apenas porque "ele corrige o problema".
precisa saber é o seguinte
7

É por isso que as empresas devem ter seu próprio repositório de conhecimento. Por exemplo, minha empresa possui um Redmine corporativo usado para gerenciamento de projetos, emissão de bilhetes (rastreamento de bugs e tarefas) e a ferramenta que mais uso, um wiki . Todos esses recursos por projeto :-)

O que temos no wiki do projeto?

  • Links para a documentação: Funcional, Técnico, Arquitetura, Requisitos.
  • Atores envolvidos: gerente de projetos, desenvolvedores, gerentes de contas principais do cliente, ...
  • Descrição por ambiente: Máquinas Virtuais, SO, servidores, configurações ...
  • Misc: Qualquer coisa importante / interessante (relacionada ao projeto) aprendida durante a vida útil do projeto.
  • Mais algumas páginas.

Coloquei bibliografia (links) no wiki Misc . Mas apenas daqueles em quem confio:

  • Stack Overflow : Votos positivos e bem argumentados
  • Troca de pilha de engenharia de software : votos positivos e bem argumentados
  • MKyong.com : Eu gosto desta página. É realmente útil e seus tutoriais são fáceis de seguir
  • MDN
  • W3C.org
  • W3Schools : Sua documentação é interativa (na maioria dos casos) e fácil de usar.
  • OWASP : Para referenciar problemas relacionados à segurança e vulnerabilidades
  • Páginas oficiais da Web: Às vezes, os melhores tutoriais ou explicações estão nas páginas oficiais da Web.

Minha bibliografia vem com um resumo digitado por mim, para garantir que eu entenda o que estou vinculando. Eu tento manter o Javadoc o mais claro possível. Cada link no código faz referência ao wiki do Redmine ou ao código de problema do Redmine.

Na ausência de ferramentas como o Redmine, achei os arquivos Markdown úteis para esses fins. No geral, os desenvolvedores devido a esses arquivos estão no SCM e vem junto com o código.

Laiv
fonte
11
Eu concordo com tudo, exceto confiar no W3Schools.com. Você pode encontrar a maior parte do que existe no MDN, que tem muito mais autoridade.
Alternatex
11
O W3schools existe há mais tempo que o MDN. Posso estar errado, mas acho que o W3schools tem mais conteúdo, tutoriais e documentação de tecnologias da web. Apesar de seus problemas, continua sendo uma das melhores referências para iniciantes, pois seu conteúdo é muito mais amigável e interativo. No lado positivo, a MDN tem uma grande comunidade apoiando seu conteúdo. Mas, no lado negativo, nunca poderia ser imparcial em sua documentação, porque possui um navegador para defender. De qualquer forma, estou de acordo com você, hoje em dia a MDN parece ter mais autoridade. se você não se importa, acrescentarei a referência à minha resposta.
Laiv 23/05
4

Os links para a Web são um tanto problemáticos como documentação, porque a Internet não garante que o conteúdo que você vê por trás deles seja o mesmo que um futuro leitor de documentos verá. Se possível, tente vincular apenas recursos que dificilmente serão alterados.

Por exemplo, quando você vincula à Wikipedia, deve vincular explicitamente à versão atual e não ao nome genérico do artigo. Para stackexchange.com, bem, no momento parece improvável que ele desapareça, mas as perguntas são editadas ou mesmo excluídas o tempo todo e, em cinco anos, pode ter surgido um novo ponto de encontro. Não me arriscaria a suspender a documentação que carrega valor comercial substancial em um site tão externo à sua organização.

Kilian Foth
fonte
"Wayback Machine - Internet Archive" (web.archive.org/) é um bom lugar para verificar se há conteúdo excluído.
Kromster 13/09/16