Apakah praktik yang buruk untuk menambahkan tautan eksternal dalam dokumentasi?

9

Seringkali saya menemukan diri saya memecahkan bug dengan menemukan jawabannya di Stack Overflow. Apakah praktik yang buruk untuk menambahkan cuplikan mengapa saya melakukan apa yang saya lakukan dan kemudian menambahkan tautan ke artikel atau halaman dari web?

documentation TruthOf42
sumber
Kemungkinan duplikat dari Haruskah saya menambahkan catatan MSDN atau tautan Stack Overflow ke kode sumber?
nyamuk
FWIW Saya selalu melakukannya, dan bahkan bertanya bagaimana melakukan ini dengan benar di StackExchange . Bukan berarti itu menjawab pertanyaan Anda, tetapi beberapa argumen untuk dan menentang dapat ditemukan di sana.
4
Kemungkinan duplikat. Apakah boleh menempatkan tautan ke situs tanya jawab dalam komentar program?
Doc Brown
Apakah pertanyaannya hanya tentang tautan (OK untuk saya), karena Anda juga menyebutkan menyalin bagian dari kode / jawaban. Ini adalah sesuatu yang hanya akan saya lakukan untuk menjelaskan algoritma atau pemrosesan yang kompleks. Struktur dan penamaan kode harus jelas terlepas dari tempat Anda membaca tentang solusi.
Kwebble

Jawaban:

14

Saya tidak berpikir itu buruk, tetapi hubungan eksternal memiliki kebiasaan buruk untuk pergi selama siklus hidup solusi. Saat melakukannya, saya sarankan untuk menempatkan ringkasan yang cukup yang akan membantu pembaca jika tautannya tidak lagi berfungsi.

Jim Rush
sumber
3
Menambahkan ringkasan berguna karena dua alasan: 1) Seperti yang ditunjukkan Jim, ini membantu pembaca memahami apakah tautannya sudah usang atau tidak, dan 2) memaksa pengembang menyalin kode dari tautan untuk memahami apa yang mereka salin. Ini membantu memastikan bahwa kode tidak hanya digunakan karena "itu memperbaiki masalah".
Mage Xy
7

Inilah sebabnya mengapa perusahaan harus memiliki repositori pengetahuannya sendiri. Sebagai contoh, perusahaan saya memiliki Redmine korporatif yang digunakan untuk manajemen proyek, ticketing (pelacakan bug dan tugas) dan alat yang paling saya gunakan, wiki . Semua fitur ini per proyek :-)

Apa yang kita miliki di wiki proyek?

  • Tautan ke dokumentasi: Fungsional, Teknis, Arsitektur, persyaratan.
  • Aktor yang terlibat: Manajer Proyek, Pengembang, manajer Akun Utama Pelanggan, ...
  • Deskripsi per lingkungan: Mesin Virtual, OS, server, konfigurasi ...
  • Lain-lain: Semua hal penting / menarik (terkait dengan proyek) yang dipelajari selama masa proyek.
  • Beberapa halaman lagi.

Saya menaruh daftar pustaka (tautan) di Misc wiki. Tetapi hanya dari mereka yang saya percayai:

Daftar pustaka saya dilengkapi dengan ringkasan yang saya ketik, untuk memastikan bahwa saya memahami apa yang saya tautkan. Saya mencoba untuk menjaga Javadoc sejelas mungkin. Setiap tautan dalam kode merujuk pada wiki Redmine atau kode masalah Redmine.

Dengan tidak adanya alat seperti Redmine, saya menemukan file Markdown berguna untuk tujuan ini. Secara keseluruhan untuk pengembang karena file-file ini ada di SCM dan disertai dengan kode.

Laiv
sumber
1
Saya setuju dengan segalanya kecuali mempercayai W3Schools.com. Anda dapat menemukan sebagian besar dari apa yang ada di MDN yang memiliki otoritas jauh lebih besar.
Alternatex
1
W3sekolah sudah ada lebih lama dari MDN. Saya mungkin salah, tetapi saya pikir W3schools memiliki lebih banyak konten, tutorial, dan dokumentasi teknologi web. Terlepas dari masalah ini, ia tetap menjadi salah satu referensi terbaik untuk pemula karena isinya jauh lebih ramah pengguna dan interaktif. Di sisi positifnya, MDN memiliki komunitas hebat yang mendukung kontennya. Tetapi di sisi negatifnya, ia tidak pernah bisa tidak memihak dalam dokumentasinya karena ia memiliki browser untuk dipertahankan. Ngomong-ngomong, saya setuju dengan Anda, sekarang MDN tampaknya memiliki otoritas lebih. jika Anda tidak keberatan, saya akan menambahkan referensi ke jawaban saya.
Laiv
4

Tautan ke web agak bermasalah sebagai dokumentasi karena internet tidak menjamin bahwa konten yang Anda lihat di belakangnya akan sama dengan yang akan dilihat oleh pembaca dokumen di masa depan. Jika memungkinkan, upayakan untuk menautkan hanya ke sumber daya yang sangat tidak mungkin berubah.

Misalnya, ketika Anda menautkan ke Wikipedia, Anda harus menautkan secara eksplisit ke versi hari ini daripada nama artikel umum. Untuk stackexchange.com, yah, saat ini tampaknya tidak akan hilang, tetapi pertanyaan diedit atau bahkan dihapus sepanjang waktu, dan dalam waktu lima tahun titik pengumpulan baru yang panas mungkin telah muncul. Saya tidak akan mengambil risiko menggantungkan dokumentasi yang membawa nilai bisnis substansial di situs yang sangat eksternal bagi organisasi Anda.

Kilian Foth
sumber
"Wayback Machine - Internet Archive" (web.archive.org/) adalah tempat yang bagus untuk memeriksa konten yang dihapus.
Kromster