Includere un collegamento alla documentazione pertinente nel messaggio di errore?

Creiamo una libreria commerciale ed esempi di codice che vengono utilizzati da sviluppatori esterni. Abbiamo una documentazione (chiusa, disponibile per gli utenti registrati) che spiega ampiamente come utilizzare la libreria.

Molti sviluppatori sono utenti principianti, quindi si verificano molti errori rudimentali.

È appropriato includere collegamenti alla documentazione nel registro degli errori? Quali sono i possibili aspetti negativi? Posso prevederne alcuni, ma sembra possibile superare quanto segue

• URL della documentazione non aggiornato
• Errori specifici della versione che non si riflettono nella documentazione più recente
• Qualcos'altro è sbagliato e stiamo sprecando il tempo dello sviluppatore inviandolo a un documento irrilevante

Di seguito un esempio di cosa intendo, è una buona idea aggiungere il testo in grassetto?

[ERRORE] Impossibile eseguire l'obiettivo org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: generate (default-cli) sul progetto standalone-pom: l'archetipo desiderato non esiste (com.example.library. archetypes: library-archetype-blank: 1.2.3.0) -> Vedi http://example.com/docs/setting-up-an-archetype per ulteriori informazioni e possibili risoluzione dei problemi

Secondo queste linee guida per i messaggi di errore e la mia esperienza, alla gente piace risparmiare tempo non leggendo la documentazione o l'aiuto. Anche google su un errore può essere al di là di loro, quindi includi un link quando hanno un motivo per fare clic su di esso.

Infine, probabilmente conosci già la prima legge di Nielsen sulla documentazione informatica: la gente non la legge. Questa scoperta è ancora più forte per i siti Web, in cui gli utenti evitano veramente qualsiasi lettura che non è essenziale per il loro compito. Clicca su Aiuto? Mai.

Gli utenti leggono la documentazione di sistema solo quando sono in difficoltà (questa è la seconda legge). Sono particolarmente attenti quando vogliono riprendersi da un errore. Detto questo, è possibile utilizzare i messaggi di errore come risorsa educativa per impartire una piccola quantità di conoscenza agli utenti. Naturalmente, i messaggi di errore dovrebbero essere brevi e pertinenti, così come tutti i contenuti Web. Tuttavia, i messaggi di errore possono ancora insegnare agli utenti un po 'su come funziona il sistema e fornire loro le informazioni di cui hanno bisogno per usarlo meglio. A tal fine, la tecnologia di base del Web rende possibile un'altra linea guida:

I collegamenti ipertestuali possono essere utilizzati per collegare un messaggio di errore conciso a una pagina con materiale di base aggiuntivo o una spiegazione del problema. (Non esagerare, però.)

Sì, sicuramente, MA:

• Il marcio del collegamento sarà un problema, idealmente genera il collegamento dinamicamente da un documento di destinazione noto ma ottiene il prefisso da una qualche forma di configurazione. Se il server dovesse cambiare, puoi mantenere valido il codice precedente aggiornando questo elemento di configurazione. Puoi anche rendere il documento disponibile localmente anche cambiando questa configurazione di prefisso.
• Controllo delle versioni : con lo stesso spirito, se è possibile includere il controllo delle versioni nel collegamento in modo che il collegamento punti sempre alla versione corretta della documentazione.
• Rendi il documento modificabile Qualcosa come un sito di tipo wiki per la tua documentazione in cui puoi correggere dinamicamente errori, idealmente permetti anche agli utenti di commentare direttamente sulla pagina. questo renderà molto più facile per i tuoi utenti la partecipazione e trovare ciò di cui hanno bisogno e otterrai informazioni d'oro per mantenere il tuo documento in buone condizioni di lavoro, ma assicurati di monitorarlo regolarmente e soprattutto di partecipare attivamente te stesso.
• I modelli generati consentono al sistema di generazione di generare direttamente il modello di base per la documentazione dalle annotazioni nel codice. Mantenerlo semplice però, ma questo assicurerà che ogni link rimanda sempre a una documentazione valida. Se usi un wiki assicurati di poter spingere facilmente questi template e assicurati di poter promuovere il sito di documentazione nello stesso modo in cui lo fai per il tuo codice (avere un sito di sviluppo diverso dal sito di prod e promuovere il codice di prod eseguire automaticamente gli inserti nel sito di produzione).

Se sviluppi con Java o .NET il documento potrebbe essere incluso in un file jar o in un file DLL e modificando il prefisso il tuo codice potrebbe invece recuperarlo localmente.

Se scegli l'approccio wiki, consiglio vivamente DokuWiki per la sua semplicità e per il fatto che si basa su file di testo semplici che lo renderebbero molto amichevole all'iniezione automatica dal sistema di compilazione. Detto questo, non so abbastanza sul tuo ambiente o sui tuoi clienti da sapere davvero se questo sarebbe un buon adattamento YMMV.

Alcuni degli strumenti di maggior successo che ho creato hanno adottato un approccio simile in cui il messaggio di errore era indirizzato all'utente reale che molto probabilmente avrebbe eseguito l'attività. Ciò significava che dovevo fare MOLTE eccezioni per intercettare e avvolgere per assicurarsi che l'errore fosse al livello di astrazione appropriato. Mi sono anche assicurato che ogni messaggio di errore includesse le fonti più probabili di errori e punti a potenziali soluzioni "Hai dimenticato di impostare il valore di configurazione xxxx?", "Assicurati che xxx e yyy non siano in conflitto dando loro nomi diversi" ecc. Dove XXX e quant'altro verrebbero generati dal contesto in cui si è verificato l'errore.

Questo approccio è stato in qualche modo più semplice ma anche più limitato. Tuttavia, ha avuto il lato positivo che la documentazione sarebbe sempre stata presente quando necessario, nessun collegamento possibile.

Il tuo approccio è la prossima evoluzione. Molto più complesso ma ha anche rendimenti molto più potenziali. Sarà costoso, ma se fatto bene si ripagherà facilmente da solo.

È preferibile puntare alla documentazione offline in bundle con la libreria, piuttosto che online.

(com.example.library.archetypes: library-archetype-blank: 1.2.3.0) -> Vedere /usr/share/myprog-3.8.1/docs/setting-up-an-archetype per ulteriori informazioni e possibili risoluzione dei problemi

(ovviamente se si tratta di una libreria di Windows, il percorso sarebbe diverso).

I vantaggi qui sono:

• In questo modo la documentazione è sempre sincronizzata con la libreria. Le persone sviluppano e risolvono problemi con le vecchie versioni delle librerie. E la tua azienda potrebbe cambiare il suo nome, cambiare il nome del prodotto o qualcuno potrebbe lasciar perdere la palla al rinnovo example.com.

• Il web cambia rapidamente. Il link che dai è http, ma tra qualche anno i suoi principali browser supporteranno solo https. O potremmo tutti tornare al gopherprotocollo.

• La risoluzione dei problemi dell'applicazione non si verifica sempre in un ambiente con accesso a Internet (o almeno accesso diretto al dominio).

• Dici che la tua documentazione è dietro un muro di "autenticazione". Dover creare un account su un sito Web solo per capire un messaggio di errore non è piacevole (ecco perché SO non richiede alle persone di accedere).

C'è un modo davvero efficace per affrontare questo problema. Assicurati che l'eccezione combinata con il messaggio sia abbastanza unica che incollandoli in una ricerca web puoi trovare facilmente tutti i post rilevanti su questo problema.

Questa è la ragione segreta che odio così tanto le eccezioni del puntatore null. Sicuramente odio che dobbiamo anche verificare la presenza di null, ma ciò che mi preoccupa di più è che, quando mi imbatto in uno, l'unico identificatore veramente univoco che devo cercare è un numero di riga volatile.

Sì, vorrei essere in grado di cercarli. Oh certo, so che è successo perché qualcosa è stato lasciato nullo e quindi utilizzato. Ciò che non è sempre immediatamente ovvio è però PERCHÉ qualcosa è stato lasciato nullo.

Quindi, considera tutte queste altre soluzioni di documentazione. Ma la cosa più pigra che puoi fare che mi farà il meglio è darmi qualcosa che posso google.

Abbastanza per favore?