Sangat menarik bagi proyek terbuka untuk berkembang dari segelintir pengguna menjadi tim kolaborator yang mengerjakan dan menggunakan perangkat lunak. Pindah dari satu ke banyak kontributor adalah momen yang kuat untuk proyek apa pun. Namun, seiring dengan skala dan pertumbuhan proyek, satu area yang sering diabaikan: dokumentasi.
Dokumentasi yang hilang atau tidak memadai menghalangi kemampuan proyek untuk menskalakan. Sebagian besar calon pengguna membaca sekilas dokumentasi Anda terlebih dahulu untuk melihat apakah itu sesuai dengan kebutuhan mereka dan untuk menilai betapa sulitnya menggunakannya. Dokumentasi membuat kesan pertama proyek Anda: tidak hanya pada pengguna potensial, tetapi juga pada kontributor potensial.
Menulis dan meningkatkan dokumentasi menawarkan jalur yang jelas bagi orang-orang untuk berkontribusi pada proyek Anda—asalkan Anda menawarkan panduan dan proses yang tepat untuk mendukung mereka. Artikel ini membahas praktik terbaik untuk menarik dan mempertahankan kontributor dokumentasi open-source berdasarkan pengalaman kami dalam membangun dan mengelola dokumentasi untuk Kubernetes.
Evaluasi dokumen Anda yang ada
Mulailah dengan mengevaluasi dokumentasi yang ada. Anda tidak dapat meminta bantuan dari kontributor Anda jika Anda tidak tahu apa yang Anda butuhkan! Saat Anda mengevaluasi dokumentasi Anda, pertimbangkan dari sudut pandang pengguna Anda:
- Apa kebutuhan pengguna saya? Apakah dokumen ini memenuhi kebutuhan mereka?
- Apakah ada fitur yang tidak didokumentasikan? Apakah informasi penting hilang? Apakah ada celah konten lain yang harus diisi?
- Konten apa yang sudah usang dan perlu dihapus?
- Konten apa yang perlu difaktorkan ulang dan diklarifikasi?
Jangan terjebak mencoba untuk memperbaiki setiap masalah yang Anda temui. Alih-alih, buka satu masalah untuk setiap masalah yang Anda temui.
Setelah Anda mengevaluasi konten Anda, tinjau masalah yang Anda buka dan tentukan apakah Anda perlu memperbaiki masalah apa pun sebelum Anda mengundang kontributor untuk mengatasinya. Misalnya, jika dokumentasi Anda terdiri dari satu halaman file `README.md` dengan 2.500 baris, memecahnya menjadi dokumen individual yang lebih kecil akan mengurangi hambatan bagi kontributor. Jika dokumentasi Anda berisi konten usang, hapus konten tersebut agar kontributor baru dapat bergabung dengan lebih mudah. Perbaiki masalah apa pun yang menurut Anda akan memblokir kontributor baru untuk mengerjakan konten Anda.
Triase masalah dokumen Anda
Proses triase masalah dokumen sederhana mungkin terlihat seperti ini:
Sekarang setelah Anda memiliki serangkaian masalah yang terkait dengan dokumentasi Anda, terapkan triase. Masalah dokumentasi triaging mirip dengan masalah kode triaging: pastikan masalah valid dan dapat ditindaklanjuti dan tetapkan prioritas.
- Validasi jika masalah terkait dengan dokumentasi Anda dan tidak terkait dengan kode Anda: Adalah umum untuk suatu masalah terkait dengan keduanya. Pertimbangkan apakah dokumentasi baru atau perubahan kode akan lebih membantu pengguna Anda. Misalnya, jika perintah CLI memiliki nama yang membingungkan, Anda dapat mendokumentasikan perintah dengan lebih baik atau mengganti nama perintah menjadi sesuatu yang lebih jelas.
- Nilai apakah masalah dapat ditindaklanjuti: Apakah masalah berisi semua yang dibutuhkan kontributor untuk memperbaiki masalah? Tandai masalah yang tidak jelas dengan sesuatu seperti `perlu informasi lebih lanjut` dan tindak lanjuti dengan orang yang mengajukan masalah tersebut. Misalnya, masalah yang hanya berbunyi, “Ini tidak berhasil,” tanpa menentukan apa yang tidak berhasil atau cara memperbaikinya tidak dapat ditindaklanjuti.
- Tetapkan prioritas untuk masalah ini: Apa yang perlu diperbaiki proyek terlebih dahulu? Anda dapat menggunakan sistem penomoran prioritas (seperti P0-P4) atau menentukan prioritas Anda dengan tag seperti `now`,`next`, dan `backlog`.
Terakhir, untuk kontributor baru, beri tag pada masalah yang merupakan perbaikan cepat atau masalah pertama yang baik. Label seperti `good first issue` memudahkan kontributor baru untuk mengidentifikasi masalah yang dapat mereka hadapi saat memulai proyek Anda.
Kubernetes menggunakan proses triase masalah dokumen yang sangat mirip dengan yang tercantum di atas.
Tambahkan proses dokumentasi ke pedoman kontributor Anda
Mudah-mudahan, Anda sudah memiliki pedoman kontributor (jika tidak, GitHub memiliki panduan hebat yang dapat Anda ikuti dalam menetapkannya). Dalam panduan Anda, sertakan panduan khusus untuk dokumentasi, termasuk:
- Bagaimana dokumentasi ditulis dan disajikan: Tunjukkan bahasa markup yang Anda gunakan, template dokumentasi apa pun yang Anda gunakan, dan apakah Anda menggunakan alat seperti generator situs statis untuk menampilkan konten Anda.
- Bagaimana dokumentasi diatur: Berikan panduan yang jelas tentang jenis konten apa yang termasuk di mana, termasuk bagaimana file dan folder diatur. Tentukan jenis konten mana yang termasuk dalam dokumentasi produk dan konten apa yang mungkin lebih cocok untuk Stack Overflow atau blog proyek Anda.
- Standar dokumentasi apa pun: Tentukan konvensi penamaan yang Anda gunakan dalam dokumentasi Anda. Anda dapat mendahului sejumlah besar pertanyaan dari kontributor Anda tentang tata bahasa, kapitalisasi, dan tanda baca dengan mengikuti panduan gaya publik. Baik Google dan Microsoft menyediakan panduan gaya dokumentasi publik.
- Panduan khusus untuk permintaan perubahan dokumen: Memberikan panduan yang jelas untuk proses kontribusi. Misalnya, tentukan cabang untuk membuka permintaan perubahan, tag apa pun yang diperlukan untuk PR dokumentasi, dan proses peninjauan tambahan apa pun yang diperlukan untuk dokumentasi.
- Jawab pertanyaan paling umum kontributor: Ketika Anda menemukan diri Anda berulang kali menjawab pertanyaan kontribusi yang sama, tambahkan pertanyaan itu (dan jawabannya) ke panduan kontribusi.
Untuk Kubernetes, kami membuat panduan kontribusi dokumentasi umum dan panduan untuk mengajukan PR dokumen.
Permudah (dan menyenangkan) untuk kontributor Anda
Dengan memberikan serangkaian masalah dan panduan yang diprioritaskan dengan jelas untuk diikuti oleh kontributor, Anda dapat meningkatkan jumlah kontributor Anda. Ingat bahwa seperti kode, proses yang Anda buat untuk dokumen memerlukan tinjauan dan pemeliharaan rutin. Tinjau masalah Anda secara teratur untuk melakukan triase dan singkirkan masalah yang sudah usang atau ketinggalan zaman.
Demikian juga, tetapkan irama reguler untuk meninjau dokumentasi PR. Edit PR dokumentasi baik untuk kualitas editorial dan teknis dan berikan kontributor Anda umpan balik yang ramah dan tepat waktu.
Terakhir, kenali kontributor dokumentasi Anda. Anda tidak perlu melakukan sesuatu yang besar seperti program bonus rekan sumber terbuka. Berterima kasih kepada kontributor dalam PR mereka, mengumumkan nama mereka saat melakukan rilis, dan secara publik berterima kasih kepada mereka atas pekerjaan mereka di blog proyek dapat menunjukkan rasa terima kasih Anda.
Jared Bhatti dan Zachary Sarah Corleissen adalah anggota Komite Emeritus SIG-Docs dari Kubernetes, dan baru-baru ini ikut menulis buku tersebut Dokumen untuk Pengembang: Panduan Lapangan Seorang Insinyur untuk Penulisan Teknis.
Tags: komunitas, dokumentasi, open source