Manajemen Repo Github jelek Anda mengecewakan kucing ini. Kamu melakukan ini.
Sebagai bioinformatician, saya berada di tengah-tengah yang menarik antara pengembang dan pengguna akhir. Pelatihan latar belakang saya dalam biologi, bukan ilmu komputer.
Namun dalam beberapa tahun terakhir, biologi telah bergerak lebih dekat ke ilmu komputer. Banyak jenis data biologis terlalu besar untuk dianalisis dengan tangan dan harus diproses menggunakan komputer. Biaya sekuens genom yang terus menurun telah memperkenalkan sejumlah besar data sekuens. Semua data ini perlu dikumpulkan, dibandingkan, dicari, dan dianotasi.
Semakin banyak, ahli biologi membutuhkan komputer.
Lebih khusus lagi, ahli biologi membutuhkan program komputer. Dengar, jika saya memiliki sekumpulan data sekuens dari mikrobiom yang saya ingin mencocokkan dengan spesies asal yang berbeda, saya tidak akan duduk dan membuat alat pelurus sendiri dari awal. Saya akan mengambil alat di luar rak digital yang telah digunakan sebelumnya, berdoa bahwa itu cukup mudah untuk dipasang, dan pasang.
Di sekolah pascasarjana, saya membuat kesalahan. Saya membiarkan kecepatan dunia komputer untuk merayu saya. "Tidak ada lagi eksperimen multi-minggu di bangku laboratorium!" Aku menyatakan pada diriku sendiri. “Saya akan terjun cepat ke sisi komputer biologi dan menjadi jembatan antara kedua dunia - bioinformatika!”
Dalam teori, seorang bioinformatika menganalisa data yang dikumpulkan oleh ahli biologi, menemukan kesimpulan baru dan membangun hubungan baru.
Dalam praktiknya, seorang bioinformatika memasang banyak program dan mengutuk pengembang yang membuatnya.
Saya sudah menyerah pada banyak program - beberapa di antaranya, saya anggap, adalah program yang sangat bagus - karena instruksi yang tidak masuk akal, kode yang buruk, atau dokumentasi yang mengerikan.
Sampai pada titik di mana saya dapat melihat repositori GitHub dan memahami bagaimana perasaan saya tentang alat Anda.
Beberapa repo menanamkan kepercayaan diri. Yang lain mengisi saya dengan ketakutan.
Terkadang, saya menemukan yang sangat buruk sehingga saya bahkan menolak untuk mencoba memasang alat (kecuali itu diminta oleh atasan saya).
Inilah masalah terbesar yang saya lihat, dan bagaimana cara menghindarinya.
Alasan 1: Tidak ada dokumentasi
Tidak ada yang tahu cara menggunakan program Anda kecuali Anda menuliskannya untuk mereka. Foto oleh Beatriz Pérez Moya.
Saya telah melihat setiap variasi dokumentasi:
Dokumentasi ditulis dalam Readme.
"Cara cepat" di ReadMe, dengan informasi mendetail dalam dokumen PDF atau Word yang terpisah.
Tautan ke wiki GitHub.
Tautan ke situs eksternal, dengan dokumentasi tertulis di sana.
Tautan ke situs eksternal, tempat ada tautan lain untuk mengunduh PDF. (Mengapa tidak memasukkan PDF dalam repo?)
Terburuk dari semua ... tidak ada dokumentasi.
Ya, saya tahu dokumentasi penulisan itu buruk. Saya telah membangun saluran pipa dan alat, dan saya memaksa diri untuk menulis dokumentasi. Saya lupa tentang kasus tepi dan detail perintah, dan terkadang menerima pengingat yang memalukan dari pengguna.
Jika Anda membuat alat dan membuatnya menjadi publik, dokumentasi Anda harus menyertakan, minimal:
Persyaratan dan ketergantungan untuk menggunakan alat Anda. Ini termasuk persyaratan perangkat keras (RAM dan ukuran disk) dan persyaratan perangkat lunak (sistem operasi, program lain).
Bagaimana menginstal alat Anda.
Apa yang dilakukan alat Anda.
Cara membuat alat Anda melakukan hal-hal tersebut, dengan perintah contoh.
Saya juga sangat menyarankan Anda untuk menyertakan:
Bagian ‘pertanyaan yang sering diajukan’.
Tes - ini termasuk data uji dan perintah yang tepat yang harus digunakan pada data uji (ke tingkat di mana perintah harus disalin / ditempelkan ke baris perintah).
Contoh output.
Lisensi.
Tangkapan layar, jika ada.
Ucapan terima kasih, apakah Anda terbuka untuk menarik permintaan, dan informasi kontak, sehingga pengguna dapat melaporkan masalah.
Dokumentasi yang buruk atau tidak lengkap adalah alasan nomor satu saya berhenti menggunakan alat. Anda tahu cara kerja alat Anda, tetapi tidak ada yang melakukannya - jangan memaksa orang untuk mengetahuinya. Berikan instruksi yang jelas dan mudah.
Alasan 2: Ketergantungan neraka
“Masing-masing ini adalah ketergantungan. Pastikan untuk membongkar semuanya dengan urutan yang benar! ”Foto oleh chuttersnap.
Saya pernah menemukan alat (pipa untuk anotasi urutan DNA) yang memiliki enam dependensi.
"Itu bukan yang terburuk," pikir saya dalam hati. "Saya bisa menangani menginstal enam dependensi untuk menggunakan alat ini."
Sayangnya, sebagian besar dependensi tersebut memiliki dependensi lain. Dan mereka memiliki lebih banyak ketergantungan, termasuk beberapa yang menolak untuk bermain dengan baik satu sama lain.
Pada saat saya menyerah pada alat asli itu, saya menemukan sembilan belas dependensi yang berbeda yang harus saya pasang, khususnya untuk menggunakan jalur pipa tunggal ini. Sembilan belas!
Sangat bagus bahwa ada banyak alat yang berguna di luar sana yang dapat berfungsi sebagai blok bangunan untuk program yang lebih kompleks. Lebih baik menggunakan ketergantungan yang sudah ada dan sudah diakui daripada memulihkan kembali roda dan melakukannya sendiri.
Tetapi jika Anda mengambil rute ini, silakan temukan cara yang lebih mudah bagi saya untuk menginstal dependensi untuk alat Anda.
Berikan saya skrip instalasi yang dapat saya jalankan untuk mendapatkan semua dependensi - ini bekerja dengan sangat baik jika saya memerlukan setengah lusin paket Python atau R. Jika memungkinkan, berikan saya arsip ketergantungan, jadi saya tidak perlu pergi dan memburunya (dengan asumsi bahwa lisensi untuk ketergantungan memungkinkan tingkat redistribusi ini).
Jangan menjebak saya dalam ketergantungan neraka - atau jika Anda melakukannya, bersiaplah untuk melihat banyak pengguna menyerah menggunakan program Anda. Tidak ada yang mau menghabiskan waktu di neraka.
Alasan 3: Masalah pengabaian
“Tidak ada yang membuat pembaruan untuk repo ini untuk waktu yang sangat lama.” Foto oleh Nathan Wright.
Ketika proyek GitHub baru dan segar, tidak ada masalah. Itu baru, bersih, dan belum ada yang menemukan bug.
Selama beberapa minggu ke depan hingga beberapa bulan, ketika pengguna menemukan program dan mengujinya, mereka akan mengangkat masalah. Untungnya, GitHub memiliki halaman di setiap repositori yang didedikasikan untuk mencatat masalah ini. Ini disebut "Masalah."
Di sini, di halaman ini, pengguna berkomentar bahwa mereka mendapatkan pesan kesalahan ketika mereka mencoba berbagai tugas. Terkadang, ini adalah ketergantungan yang sudah kedaluwarsa. Terkadang, itu salah ketik dalam kode. Terkadang, itu adalah kesalahan pengguna - mereka memiliki versi yang salah dari alat lain, masukan mereka dalam format yang salah, atau mereka menggunakan opsi ilegal dan tidak membaca pesan bantuan.
Di permukaan, ini adalah fitur hebat. Tapi halaman Masalah ini juga bisa menjadi peringatan - atau jera.
Halaman Masalah dapat memunculkan salah satu dari dua bendera merah - atau bendera hijau:
Bendera merah 1: Tidak ada masalah. Tidak pernah ada masalah. Tidak seorang pun pernah menggunakan alat ini, dan alat ini ditinggalkan dan mengumpulkan debu.
Red flag 2: Ada beberapa masalah terbuka, kebanyakan tentang kesalahan, tanpa resolusi dari pemilik repo. Alat ini ditinggalkan dan rusak dan pemiliknya tidak peduli.
Bendera hijau: Hanya ada sedikit masalah terbuka, sebagian besar ditandai sebagai penyempurnaan - tetapi banyak masalah tertutup. Pemiliknya secara aktif memperbaiki kesalahan, membantu pengguna, dan berencana menambahkan lebih banyak fitur.
Karena saya telah mempublikasikan program di GitHub, saya tahu bahwa mempertahankannya tidak menyenangkan. Menyenangkan untuk membuat sesuatu yang baru. Tidaklah menyenangkan untuk memecahkan masalah pesan kesalahan aneh dan menggunakan kasus penggunaan. Tidak menyenangkan untuk menuangkan kembali halaman kode lama dan mencari tahu mengapa kondisi super spesifik menyebabkan kegagalan.
Tetapi program terbaik (dan repositori GitHub yang paling tepercaya) berasal dari para pembuat konten yang bersedia melakukan pekerjaan membosankan dan membosankan. Itu termasuk memperbaiki masalah dan memberikan dukungan untuk pengguna.
Dan jika ada pertanyaan lain yang dijawab, saya merasa lebih yakin bahwa masalah saya sendiri akan ditangani, dan saya akan dapat menggunakan alat ini dengan percaya diri untuk tujuan saya sendiri.
Jual saya di program Anda
Suka atau tidak, repositori GitHub Anda sering menjadi 'wajah' dari program Anda. Repo Anda perlu menjual program Anda karena mudah dipasang, mudah dijalankan, dan mudah dimengerti.
Reputasi GitHub yang hebat adalah hal yang indah. Sebagai pengguna semi-terampil, saya suka ketika file readme memberi tahu saya apa perintah untuk menginstal alat, bagaimana menggunakannya, dan bagaimana memecahkan masalah yang paling umum. Sebuah panduan yang terperinci dan lugas menempatkan senyum di wajah saya. Skrip penginstalan satu langkah membuat saya bernapas lega. Indikasi bahwa Anda mendukung alat dan memperbaiki bug menyebabkan dada saya dipenuhi dengan percaya diri.
Biarkan saya menggunakan alat Anda.
Biarkan saya mengutip pekerjaan Anda dan nyanyikan pujian Anda kepada rekan-rekan saya.
Biarkan saya menghormati Anda dan program hebat yang Anda buat.
Hindari masalah ini - dan hindari kesalahan ini di repositori GitHub Anda yang menghadap publik berikutnya.
Sam Westreich adalah ilmuwan mikrobiom yang bekerja di Silicon Valley, dan telah menghabiskan waktu bertahun-tahun membenamkan diri dalam sains dan hal-hal yang paling buruk dalam pengejaran. Dia menulis tentang sains, biologi, mikroba dan mikrobioma, dan pemikirannya tentang sekolah pascasarjana dan menemukan kesuksesan.
Tidak ada komentar
Posting Komentar