Includere un collegamento alla relativa documentazione nel messaggio di errore?

In base a queste linee guida per i messaggi di errore e alla mia esperienza, alle persone piace risparmiare tempo non leggere documentazione o aiuto. Anche cercare su Google un errore può essere al di là di esse, quindi includi un link quando hanno un motivo per selezionarlo.

Finally, you probably already know Nielsen's First Law of Computer Documentation: people don't read it. This finding is even stronger for websites, where users truly shy away from any reading that is not essential to their task. Click on Help? Never.

Users read system documentation only when they are in trouble (that's the Second Law). They are particularly attentive when they want to recover from an error. Given this, you can use error messages as an educational resource to impart a small amount of knowledge to users. Of course, error messages should be brief and to the point, as should all Web content. However, error messages can still teach users a bit about how the system works and give them information they need to use it better. To further that end, the Web's underlying technology makes another guideline possible:

Hypertext links can be used to connect a concise error message to a page with additional background material or an explanation of the problem. (Don't overdo this, though.)

Sì in modo definitivo MA:

• Link rot sta per essere un problema, Idealmente generare il collegamento dinamicamente da un documento di destinazione noto ma ottenere il prefisso da una qualche forma di configurazione. Se il server cambia, puoi mantenere valido il vecchio codice aggiornando questo elemento di configurazione. Puoi anche rendere disponibile localmente il documento anche modificando questa configurazione di prefisso.
• Versioning : nello stesso spirito, se è possibile includere il controllo delle versioni nel collegamento in una certa capacità in modo che il collegamento rimandi sempre alla versione corretta della documentazione.
• Rendi modificabile il documento Qualcosa come un sito di tipo wiki per la tua documentazione in cui puoi correggere in modo dinamico gli errori, idealmente anche consentire agli utenti di commentare direttamente sulla pagina. questo renderà molto più facile per i tuoi utenti partecipare 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 partecipare attivamente a se stessi.
• Modelli generati fai in modo che il tuo sistema di generazione generi direttamente il modello di base per la documentazione dalle annotazioni nel codice. Mantenerlo semplice, ma questo garantirà che ogni link punti sempre a una documentazione valida. Se usi una wiki, assicurati di poter spingere questi modelli facilmente, e assicurati di poter promuovere il sito della documentazione nello stesso modo in cui lo fai per il tuo codice (hai un sito di sviluppo diverso dal sito di produzione e promuovi codice per prod eseguire gli inserimenti nel sito prod automaticamente).

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

Se scegli l'approccio wiki, raccomando vivamente DokuWiki per la sua semplicità e per il fatto che si basa su un testo piatto file che renderebbero molto facile l'iniezione automatica dal sistema di build. Detto questo, non ne so abbastanza del tuo ambiente o dei tuoi clienti per sapere se questo potrebbe essere un buon YMMV.

Alcuni degli strumenti di maggior successo che ho creato hanno adottato un approccio simile in cui il messaggio di errore è stato indirizzato all'utente reale che avrebbe probabilmente eseguito l'attività. Ciò significava che dovevo fare un sacco di eccezioni catching e wrapping per assicurarmi che l'errore fosse al livello appropriato di astrazione. Mi sono anche assicurato che ogni messaggio di errore includesse le fonti più probabili di errori e indicasse le 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 whatnot verrebbero generati dal contesto in cui si è verificato l'errore.

Questo approccio era un po 'più semplice ma anche più limitato. Aveva tuttavia il vantaggio che la documentazione fosse sempre presente quando non era necessario alcun collegamento.

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

Dovresti privilegiare il puntamento alla documentazione offline in bundle con la libreria, piuttosto che online.

(com.example.library.archetypes:library-archetype-blank:1.2.3.0) -> Please see /usr/share/myprog-3.8.1/docs/setting-up-an-archetype for more information and possible troubleshooting

(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 le vecchie versioni di libreria. E la tua azienda potrebbe cambiare nome, cambiare il nome del prodotto o qualcuno potrebbe lasciar cadere la palla al rinnovo di example.com .

• Il web cambia rapidamente. Il link che fornisci è http , ma tra qualche anno probabilmente il suo maggiore i browser supportano solo https . O potremmo tutti tornare al protocollo gopher .

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

• Hai menzionato che la tua documentazione è dietro un muro di "autenticazione". Dovendo creare un account su un sito web solo per capire un messaggio di errore non è piacevole (questo è il motivo per cui 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 da incollarli in una ricerca sul Web e trovare facilmente tutti i post pertinenti su esattamente questo problema.

Questa è la ragione segreta che odio così tanto le eccezioni dei puntatori nulli. Certo odio che dovremmo anche verificare la presenza di null ma ciò che mi infastidisce di più è che, quando ne incontro uno, l'unico identificatore univoco che devo cercare è un numero di linea volatile.

Sì, mi piacerebbe essere in grado di cercare questi. Oh certo, so che è successo perché qualcosa è stato lasciato null e poi usato. Ciò che non è sempre immediatamente ovvio, però, è perché WHY è stato lasciato nulla.

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

Pretty Please?