Sertakan tautan ke dokumentasi yang relevan dalam pesan kesalahan?

Kami membuat perpustakaan komersial dan contoh kode yang digunakan oleh pengembang eksternal. Kami memiliki (tertutup, tersedia untuk pengguna terdaftar) dokumentasi yang secara luas menjelaskan cara menggunakan perpustakaan.

Banyak pengembang adalah pengguna pertama kali, sehingga banyak kesalahan mendasar yang ditemui.

Apakah pantas memasukkan tautan ke dokumentasi di log kesalahan? Apa kemungkinan kerugiannya? Saya dapat meramalkan beberapa, tetapi tampaknya mungkin untuk mengatasi yang berikut ini

• URL dokumentasi ketinggalan zaman
• Kesalahan spesifik versi yang tidak tercermin dalam dokumentasi terbaru
• Ada hal lain yang salah, dan kami menyia-nyiakan waktu pengembang dengan mengirimkannya ke dokumen yang tidak relevan

Di bawah ini contoh dari apa yang saya maksud, apakah ide yang baik untuk menambahkan teks tebal?

[GALAT] Gagal menjalankan tujuan org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: menghasilkan (default-cli) pada proyek standalone-pom: Pola dasar yang diinginkan tidak ada (com.example.library. arketipe: library-archetype-blank: 1.2.3.0) -> Silakan lihat http://example.com/docs/setting-up-an-archetype untuk informasi lebih lanjut dan kemungkinan pemecahan masalah

Menurut pedoman pesan kesalahan ini , dan pengalaman saya, orang suka menghemat waktu dengan tidak membaca dokumentasi atau bantuan. Menelusuri kesalahan Google juga mungkin ada di luarnya, jadi sertakan juga tautan saat mereka memiliki alasan untuk mengkliknya.

Akhirnya, Anda mungkin sudah tahu Hukum Pertama Dokumentasi Komputer Nielsen: orang tidak membacanya. Temuan ini bahkan lebih kuat untuk situs web, di mana pengguna benar-benar menghindar dari bacaan apa pun yang tidak penting untuk tugas mereka. Klik Bantuan? Tidak pernah.

Pengguna membaca dokumentasi sistem hanya ketika mereka dalam kesulitan (itulah Hukum Kedua). Mereka sangat perhatian ketika mereka ingin pulih dari kesalahan. Dengan ini, Anda dapat menggunakan pesan kesalahan sebagai sumber daya pendidikan untuk memberikan sedikit pengetahuan kepada pengguna. Tentu saja, pesan kesalahan harus singkat dan to the point, sebagaimana seharusnya semua konten Web. Namun, pesan kesalahan masih dapat mengajarkan pengguna sedikit tentang cara kerja sistem dan memberi mereka informasi yang mereka butuhkan untuk menggunakannya dengan lebih baik. Untuk mencapai tujuan itu, teknologi yang mendasari Web memungkinkan pedoman lain:

Tautan hiperteks dapat digunakan untuk menghubungkan pesan kesalahan singkat ke halaman dengan bahan latar belakang tambahan atau penjelasan masalah. (Namun, jangan berlebihan melakukannya.)

Ya paling pasti TETAPI:

• Pembusukan tautan akan menjadi masalah, idealnya menghasilkan tautan secara dinamis dari dokumen target yang diketahui tetapi mendapatkan awalan dari beberapa bentuk konfigurasi. Jika server berubah maka Anda dapat menjaga kode yang lebih lama valid dengan memperbarui elemen konfigurasi ini. Anda juga dapat membuat dokumen tersedia secara lokal juga hanya dengan mengubah konfigurasi awalan ini.
• Versi : Dengan semangat yang sama, jika Anda dapat menyertakan versi dalam tautan dalam beberapa kapasitas sehingga tautan selalu mengarah ke versi dokumentasi yang benar.
• Jadikan dokumen dapat diedit Sesuatu seperti situs jenis wiki untuk dokumentasi Anda di mana Anda dapat memperbaiki kesalahan secara dinamis, idealnya juga memungkinkan pengguna untuk berkomentar langsung pada halaman. ini akan membuat lebih mudah bagi pengguna Anda untuk berpartisipasi dan menemukan apa yang mereka butuhkan dan Anda akan mendapatkan informasi emas untuk menjaga dokumen Anda dalam kondisi kerja yang baik tetapi pastikan Anda memantau secara teratur dan sebagian besar dari semua berpartisipasi secara aktif sendiri.
• Templat yang dihasilkan meminta sistem build Anda membuat templat dasar untuk dokumentasi dari anotasi dalam kode secara langsung. Tetap sederhana, tetapi ini akan memastikan bahwa setiap tautan selalu mengarah ke dokumentasi yang valid. Jika Anda menggunakan wiki pastikan Anda dapat mendorong templat ini dengan mudah, dan pastikan Anda dapat mempromosikan situs dokumentasi dengan cara yang sama seperti yang Anda lakukan untuk kode Anda (memiliki situs pengembang yang berbeda dari situs prod dan mempromosikan kode ke prod akan melakukan sisipan di situs prod secara otomatis).

Jika Anda mengembangkan dengan Java atau .NET dokumen tersebut dapat dimasukkan dalam file jar atau file DLL dan dengan mengubah awalan kode Anda bisa mengambilnya secara lokal.

Jika Anda benar-benar memilih pendekatan wiki, saya sangat merekomendasikan DokuWiki untuk kesederhanaannya dan karena itu didasarkan pada file teks datar yang akan membuatnya sangat ramah untuk injeksi otomatis dari sistem build. Yang mengatakan, saya tidak cukup tahu tentang lingkungan Anda atau pelanggan untuk benar-benar tahu apakah ini akan cocok YMMV.

Beberapa alat paling sukses yang saya buat mengambil pendekatan serupa di mana pesan kesalahan ditargetkan ke pengguna aktual yang kemungkinan besar akan melakukan tugas. Itu berarti bahwa saya harus BANYAK pengecualian menangkap dan membungkus untuk memastikan kesalahan berada pada tingkat abstraksi yang sesuai. Saya juga memastikan bahwa setiap pesan kesalahan akan menyertakan sumber kesalahan yang paling mungkin dan menunjuk ke solusi potensial "Apakah Anda lupa untuk menetapkan nilai konfigurasi xxxx?", "Pastikan xxx dan yyy tidak bertentangan dengan memberi mereka nama yang berbeda" dll. Di mana XXX dan yang lainnya akan dihasilkan dari konteks di mana kesalahan terjadi.

Pendekatan ini agak sederhana tetapi juga lebih terbatas. Namun ada sisi positifnya bahwa dokumentasi akan selalu ada ketika tidak diperlukan pembusukan tautan.

Pendekatan Anda adalah evolusi selanjutnya. Jauh lebih kompleks tetapi juga memiliki potensi pengembalian yang jauh lebih besar. Meskipun akan mahal tetapi jika dilakukan dengan benar akan dengan mudah membayar sendiri.

Anda harus lebih memilih menunjuk ke dokumentasi offline yang dibundel dengan perpustakaan, daripada online.

(com.example.library.archetypes: library-archetype-blank: 1.2.3.0) -> Silakan lihat /usr/share/myprog-3.8.1/docs/setting-up-an-archetype untuk informasi lebih lanjut dan kemungkinan pemecahan masalah

(jelas jika itu adalah pustaka Windows, jalurnya akan berbeda).

Manfaatnya di sini adalah:

• Dengan cara ini, dokumentasi selalu disinkronkan dengan perpustakaan. Orang-orang berkembang dengan dan memecahkan masalah versi perpustakaan lama. Dan perusahaan Anda dapat mengubah namanya, mengubah nama produk, atau seseorang mungkin gagal dalam memperbaharui example.com.

• Web berubah dengan cepat. Tautan yang Anda berikan adalah http, tetapi dalam beberapa tahun kemungkinan peramban utama hanya akan mendukung https. Atau kita semua bisa kembali ke gopherprotokol.

• Pemecahan masalah aplikasi tidak selalu terjadi di lingkungan dengan akses internet (atau setidaknya akses langsung ke domain Anda).

• Anda menyebutkan dokumentasi Anda ada di balik dinding "otentikasi". Harus membuat akun di situs web hanya untuk memahami pesan kesalahan tidak menyenangkan (inilah sebabnya SO tidak mengharuskan orang untuk masuk).

Ada cara yang sangat sukses untuk mendekati masalah ini. Pastikan pengecualian yang dikombinasikan dengan pesan cukup unik sehingga menempelkannya ke pencarian web dapat dengan mudah menemukan semua posting yang relevan tentang masalah ini.

Ini adalah alasan rahasia saya sangat membenci pengecualian null pointer. Tentu saya benci bahwa kita bahkan harus memeriksa nol tetapi yang paling mengganggu saya adalah, ketika saya bertemu dengan satu, satu-satunya pengidentifikasi unik yang harus saya cari adalah nomor baris yang mudah berubah.

Ya, saya ingin dapat mencari ini. Oh tentu, saya tahu itu terjadi karena sesuatu dibiarkan nol dan kemudian digunakan. Apa yang tidak selalu segera jelas adalah MENGAPA sesuatu dibiarkan nol.

Jadi yakin, pertimbangkan semua solusi dokumentasi lainnya ini. Tetapi hal paling malas yang dapat Anda lakukan yang akan membuat saya paling baik adalah hanya memberi saya sesuatu yang saya bisa google.

Cukup Cantik?