Incluir um link para a documentação relevante na mensagem de erro?

Criamos uma biblioteca comercial e exemplos de código que estão sendo usados ​​por desenvolvedores externos. Temos (fechado, disponível para usuários registrados) documentação que explica extensivamente como usar a biblioteca.

Muitos dos desenvolvedores são usuários iniciantes, então muitos erros rudimentares são encontrados.

É apropriado incluir links para a documentação no log de erros? Quais são as possíveis desvantagens? Eu posso prever alguns, mas parece possível superar o seguinte

• URL da documentação desatualizado
• Erros específicos da versão que não são refletidos na documentação mais recente
• Outra coisa está errada, e estamos perdendo o tempo do desenvolvedor enviando-o para um documento irrelevante

Abaixo um exemplo do que quero dizer, é uma boa ideia adicionar o texto em negrito?

[ERRO] Falha ao executar a meta org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: generate (default-cli) no projeto standalone-pom: O arquétipo desejado não existe (com.example.library. archetypes: library-archetype-blank: 1.2.3.0) -> Consulte http://example.com/docs/setting-up-an-archetype para obter mais informações e possíveis soluções de problemas

De acordo com essas diretrizes de mensagens de erro e com a minha experiência, as pessoas gostam de economizar tempo não lendo a documentação ou a ajuda. A pesquisa de um erro também pode estar além deles, por isso inclua um link quando tiverem um motivo para clicar nele.

Por fim, você provavelmente já conhece a Primeira Lei de Documentação Computacional de Nielsen: as pessoas não a leem. Essa descoberta é ainda mais forte para sites, onde os usuários realmente evitam qualquer leitura que não seja essencial para sua tarefa. Clique em Ajuda? Nunca.

Os usuários leem a documentação do sistema somente quando estão com problemas (essa é a Segunda Lei). Eles estão particularmente atentos quando desejam se recuperar de um erro. Diante disso, você pode usar as mensagens de erro como um recurso educacional para transmitir uma pequena quantidade de conhecimento aos usuários. Obviamente, as mensagens de erro devem ser breves e objetivas, assim como todo o conteúdo da Web. No entanto, as mensagens de erro ainda podem ensinar aos usuários um pouco sobre como o sistema funciona e fornecer as informações necessárias para usá-lo melhor. Para promover esse objetivo, a tecnologia subjacente da Web possibilita outra orientação:

Os links de hipertexto podem ser usados ​​para conectar uma mensagem de erro concisa a uma página com material de segundo plano adicional ou uma explicação do problema. (Não exagere, no entanto.)

Sim, definitivamente, MAS:

• A podridão do link será um problema. Idealmente, gere o link dinamicamente a partir de um documento de destino conhecido, mas obtenha o prefixo de alguma forma de configuração. Se o servidor mudar, você poderá manter o código antigo válido, atualizando este elemento de configuração. Você também pode disponibilizar o documento localmente apenas alterando esta configuração de prefixo.
• Controle de versão : no mesmo espírito, se você puder incluir controle de versão no link de alguma forma, para que o link sempre aponte para a versão correta da documentação.
• Torne o documento editável Algo como um site do tipo wiki para a sua documentação, onde você pode corrigir erros dinamicamente, idealmente, também permita que os usuários comentem diretamente na página. isso tornará muito mais fácil a participação dos usuários e o que eles precisam, e você obterá informações de ouro para manter seu documento em boas condições de trabalho, mas certifique-se de monitorá-lo regularmente e, acima de tudo, participe ativamente.
• Modelos gerados fazem com que seu sistema de construção gere o modelo básico para a documentação a partir de anotações no código diretamente. Porém, mantenha as coisas simples, mas isso garantirá que todos os links sempre aponte para uma documentação válida. Se você usa um wiki, certifique-se de poder empurrar esses modelos facilmente e promover o site de documentação da mesma maneira que para o seu código (tenha um site de desenvolvimento diferente do site de prod e promova o código para prod. execute as inserções no site do produto automaticamente).

Se você desenvolver com Java ou .NET, o documento poderá ser incluído em um arquivo jar ou DLL e, alterando o prefixo, seu código poderá buscá-lo localmente.

Se você escolher a abordagem wiki, recomendo o DokuWiki por sua simplicidade e pelo fato de ser baseado em arquivos de texto simples, o que tornaria muito fácil a injeção automatizada do sistema de compilação. Dito isto, eu não sei o suficiente sobre seu ambiente ou clientes para realmente saber se isso seria um bom ajuste para o YMMV.

Algumas das ferramentas mais bem-sucedidas que eu criei adotaram uma abordagem semelhante, na qual a mensagem de erro foi direcionada ao usuário real que provavelmente executaria a tarefa. Isso significava que eu tinha que fazer muitas exceções de captura e empacotamento para garantir que o erro estivesse no nível apropriado de abstração. Também assegurei-me de que cada mensagem de erro incluísse as fontes mais prováveis ​​de erros e aponte para possíveis soluções "Você esqueceu de definir o valor da configuração xxxx?", "Verifique se xxx e yyy não conflitam, fornecendo nomes diferentes" etc. Onde XXX e outros enfeites seriam gerados a partir do contexto em que o erro ocorreu.

Essa abordagem foi um pouco mais simples, mas também mais limitada. No entanto, havia a vantagem de que a documentação sempre estaria presente quando necessário, sem a possibilidade de roteamento de link.

Sua abordagem é a próxima evolução. Muito mais complexo, mas também com retornos muito mais potenciais. Porém, será caro, mas, se bem feito, será recompensado com facilidade.

Você deve preferir apontar para a documentação offline fornecida com a biblioteca, em vez de online.

(com.example.library.archetypes: library-archetype-blank: 1.2.3.0) -> Consulte /usr/share/myprog-3.8.1/docs/setting-up-an-archetype para obter mais informações e possíveis soluções de problemas

(obviamente, se for uma biblioteca do Windows, o caminho seria diferente).

Os benefícios aqui são:

• Dessa forma, a documentação está sempre sincronizada com a biblioteca. As pessoas desenvolvem e solucionam problemas de versões antigas da biblioteca. E sua empresa pode mudar seu nome, mudar o nome do produto ou alguém pode desistir da renovação example.com.

• A web muda rapidamente. O link que você fornece é http, mas em alguns anos seus prováveis ​​principais navegadores apenas serão compatíveis https. Ou todos nós podemos voltar ao gopherprotocolo.

• A solução de problemas de aplicativos nem sempre ocorre em um ambiente com acesso à Internet (ou pelo menos acesso direto ao seu domínio).

• Você mencionou que sua documentação está atrás de um muro de "autenticação". Ter que criar uma conta em um site apenas para entender uma mensagem de erro não é agradável (é por isso que o SO não exige que as pessoas façam login).

Existe uma maneira realmente bem-sucedida de abordar esse problema. Verifique se a exceção combinada com a mensagem é única o suficiente para que colá-las em uma pesquisa na web encontre facilmente todas as postagens relevantes sobre exatamente esse problema.

Esta é a razão secreta pela qual odeio tanto as exceções de ponteiros nulos. É claro que odeio que tenhamos que procurar nulo, mas o que mais me incomoda é que, quando encontro um, o único identificador verdadeiramente único que tenho que pesquisar é um número de linha volátil.

Sim, eu gostaria de poder procurar por eles. Ah, claro, eu sei que aconteceu porque algo foi deixado nulo e depois usado. O que nem sempre é óbvio imediatamente é por que algo foi deixado nulo.

Portanto, considere todas essas outras soluções de documentação. Mas a coisa mais preguiçosa que você pode fazer e que me fará mais bem é me dar algo que eu possa pesquisar no Google.

Pretty Please?