Season of Docs adalah program keberlanjutan yang dikelola oleh Google Open Source Programs Office. Tujuan Season of Docs adalah:
- Memberikan dukungan untuk project open source dalam memecahkan masalah project dengan dokumentasi
- Memberikan peluang kepada penulis teknis untuk mendapatkan pengalaman di open source
- Meningkatkan kesadaran tentang open source, dokumentasi, dan penulisan teknis
- Mengumpulkan dan membagikan informasi tentang metrik yang efektif dalam dokumentasi open source
Informasi selengkapnya tentang Season of Docs tersedia di situs program.
Ringkasan program 2022
Cara kerja Season of Docs
Di Season of Docs, organisasi mengajukan permohonan dengan mengirimkan proposal project. Proposal project mencakup:
- Informasi tentang organisasi
- Deskripsi masalah yang dihadapi project
- Cara project menggunakan dokumentasi untuk membantu memecahkan masalah
- Cara project mengukur efektivitas dokumentasinya (metrik)
- Linimasa untuk pekerjaan
- Anggaran project
- Informasi tambahan apa pun, seperti pengalaman organisasi dalam program serupa, atau hal lain yang akan membantu administrator Season of Docs memahami project dan masalahnya
Setelah diterima dalam program, organisasi merekrut dan mempekerjakan penulis teknis mereka sendiri secara langsung. Season of Docs menggunakan Open Collective untuk mendanai organisasi, dan organisasi membayar penulis teknis melalui Open Collective. Anggaran dan pembayaran project bersifat transparan; anggaran disertakan dalam proposal project organisasi yang tersedia di situs Season of Docs, dan pembayaran dapat dilihat di akun Open Collective Season of Docs.
Organisasi dianggap telah berhasil menyelesaikan program saat mereka mengirimkan laporan studi kasus. Organisasi juga diminta untuk menyelesaikan evaluasi bulanan selama program dan tiga survei tindak lanjut triwulanan selama tahun setelah penyelesaian program.
Sorotan 2022
“Setelah dokumen baru dirilis, kunjungan harian ke Casbin dan Casdoor hampir dua kali lipat, dan rasio pantulan turun sekitar 30%.”—Casbin
“Hasil yang menyenangkan dari project ini adalah melihat [penulis teknis kami] berkembang menjadi peran kepemimpinan di komunitas kami. Kedua kontributor kini memimpin rapat kelompok kerja dan komunitas, serta berkontribusi pada desain dan pemeliharaan project kami.” —moja-global
“[GSoD] membantu kami merekrut dua penulis teknis berbakat yang sangat sulit ditemukan dalam penyiapan reguler, yang terus menjadi kontributor OS aktif untuk OpenMined, dan yang telah memberikan pengalaman kerja yang luar biasa bagi kami.” —OpenMined
“Selain itu, panduan baru ini jauh lebih mudah dipahami oleh pemula di bidang spektrometri massa komputasi. Untuk mengilustrasikan hal ini: hibah CZI juga memberikan tunjangan untuk individu yang secara historis kurang beruntung dan beberapa penerima hibah telah menggunakan panduan OpenMS baru untuk memulai periode magang selama enam minggu dan memberikan ulasan positif tentang panduan baru tersebut.” —OpenMS
Data ringkasan 2022
Pada tahun 2022, program Season of Docs menerima 31 project dari 67 permohonan, dan 30 project berhasil menyelesaikan program. Dari 31 organisasi yang diterima, 17 organisasi adalah pemohon berulang.
31 project yang diterima mempekerjakan 58 penulis teknis. Lebih dari 190 penulis teknis menunjukkan minat mereka untuk berpartisipasi dalam program dengan menambahkan informasi kontak dan link ke portofolio mereka di repo GitHub Season of Docs.
Untuk program 2022:
- 100% organisasi memiliki pengalaman positif dengan proses permohonan
- 100% organisasi memiliki pengalaman positif dengan dokumentasi/konten situs program
- 93% organisasi memiliki pengalaman positif dengan program
- 90% organisasi merasa project dokumentasi mereka berhasil
Tentang organisasi
Organisasi yang berpartisipasi dalam Season of Docs 2022 mewakili berbagai project open source. Cohort 2022 mencakup:
- Alat pengembangan, seperti AsyncAPI dan SpyderIDE
- Bahasa dan framework pemrograman, seperti Julia, LFortran, R, dan p5.js
- Project ilmiah, seperti CERN-HSF dan SymPy
- Aplikasi pengguna akhir, seperti Mautic, Open Food Facts, Talawa, dan Ushahidi
- Project hardware dan robotik, seperti ExpressLRS dan Open-RMF
- Project data, seperti GeomScale, GeomStats, OpenMined, dan Weaviate
- Project cloud dan infrastruktur, seperti cert-manager, NimbleEdge, dan Cilium
Kami tidak mengumpulkan metadata apa pun tentang project (seperti tanggal didirikan, distribusi geografis kontributor, jumlah kontributor, atau ukuran basis pengguna).
Kami meminta project untuk menunjukkan lisensi open source yang mereka gunakan.
Tentang project dokumentasi
Masalah dokumentasi
Masalah utama yang diharapkan dapat diselesaikan oleh organisasi dengan dokumentasi dalam program 2022 mencakup:
Perhatikan bahwa organisasi dapat melaporkan beberapa masalah dokumentasi. Untuk mengetahui detail selengkapnya, lihat halaman hasil Season of Docs 2022 results page, yang menautkan ke proposal project asli dan studi kasus lengkap untuk setiap organisasi.
Jenis dokumentasi yang dibuat
Dokumentasi panduan adalah jenis dokumentasi yang paling sering disebutkan dalam studi kasus 2022.
Jenis dokumentasi lain yang disebutkan dalam studi kasus mencakup:
- Panduan memulai
- Glosarium
- FAQ
- Basis pengetahuan
- Komponen
- Konten blog/media sosial
- Panduan pengelola
Beberapa kategori ini tidak jelas dan satu project dokumentasi dapat berisi beberapa jenis atau fitur dokumentasi.
Untuk mengetahui detail selengkapnya, lihat halaman hasil Season of Docs 2022 results page, yang menautkan ke proposal project asli dan studi kasus lengkap untuk setiap organisasi.
Anggaran
Permintaan anggaran rata-rata adalah $11.679 dan mediannya adalah $12.150. Lima organisasi meminta dan menerima hibah tertinggi yang tersedia ($15 ribu) dan tiga organisasi meminta hibah terendah (antara $5 ribu-$7 ribu).
Metrik
Project menguraikan dalam studi kasus metrik yang mereka gunakan untuk mengukur keberhasilan project dokumentasi.
Metrik yang paling banyak diusulkan adalah:
Metrik lain yang diusulkan mencakup:
- Lebih banyak permintaan pull/kontribusi dokumentasi
- Lebih banyak masukan langsung di halaman dokumentasi
- Waktu yang dihabiskan di halaman
- Masalah yang diajukan (sebagai proxy untuk penggunaan)
- Peserta di forum
- Jumlah partner/sukarelawan/integrasi
- Rasio pantulan yang lebih rendah
- Peningkatan kesadaran di komunitas.
Karena waktu yang singkat antara penyelesaian project penulisan teknis dan pengiriman studi kasus, sebagian besar cohort 2022 belum dapat mengumpulkan data yang cukup pada saat mengirimkan studi kasus untuk menentukan apakah metrik awal mereka telah terpenuhi atau tidak.
Saat kami menerima jawaban atas survei tindak lanjut pada tahun 2023, kami akan memperbarui laporan ini untuk menambahkan informasi tentang project mana yang telah mencapai metriknya atau merevisi metriknya.
Untuk mengetahui detail selengkapnya, lihat halaman hasil Season of Docs 2022 results page, yang menautkan ke proposal project asli dan studi kasus lengkap untuk setiap organisasi.
Bekerja sama dengan penulis teknis
Dalam program Season of Docs, project diharapkan merekrut, mewawancarai, mempekerjakan, dan membayar penulis teknis secara langsung. Penulis teknis dapat menambahkan diri mereka ke direktori yang dikelola oleh Season of Docs di repo GitHub kami, tetapi staf Season of Docs tidak memeriksa atau merekomendasikan penulis teknis.
Praktik terbaik untuk mempekerjakan penulis teknis untuk project open source
Project diminta untuk membagikan praktik terbaik mereka dalam merekrut, mempekerjakan, dan bekerja sama dengan penulis teknis. Rekomendasi utamanya adalah:
Perekrutan
- Wawancarai lebih sedikit kandidat, dan gunakan sesi latihan langsung, bukan hanya meninjau CV
- Utamakan keterampilan komunikasi tertulis dan lisan daripada kemahiran dalam bahasa atau alat project Anda
- Ajukan pertanyaan langsung tentang cara penulis teknis akan memperoleh pengetahuan domain yang diperlukan untuk bekerja dengan project Anda
- Seseorang yang antusias dengan misi project Anda dan yang memiliki nilai inti open source cenderung akan tetap termotivasi selama seluruh project
- Terbukalah terhadap pelamar dari seluruh dunia, karena keberagaman sudut pandang dan latar belakang akan membantu project Anda—tetapi perlu diingat bahwa memiliki penulis dan mentor di terlalu banyak zona waktu yang berbeda dapat memerlukan banyak upaya ekstra untuk menjaga komunikasi yang baik
Perekrutan
- Gunakan kontrak yang secara jelas menjelaskan hasil kerja, jadwal pembayaran, dan komitmen waktu tertentu
- Jika project Anda memiliki banyak hal yang tidak diketahui, sertakan tonggak capaian untuk penemuan atau riset yang terpisah dari pembuatan dokumentasi
Koordinasi dan komunikasi
- Buat log rapat yang mencatat keputusan untuk memudahkan semua orang yang mengerjakan project memahami konteks dan langkah berikutnya
- Jelaskan dengan jelas komunikasi yang diharapkan dan seberapa sering, baik itu panggilan mingguan, email harian, atau update status di channel chat
- Berikan respons dan masukan yang jelas yang mencakup 'mengapa' dan bukan hanya 'apa’
- Hubungkan penulis teknis Anda dengan komunitas yang lebih luas untuk memberi mereka konteks dan mempromosikan pekerjaan mereka
Proses dan alat
- Buat proses dokumentasi yang akan berlangsung di luar program Season of Docs, dan yang dapat dikontribusikan oleh seluruh komunitas
- Peninjauan dokumentasi akan memerlukan waktu setidaknya sama panjang dan sama intensifnya dengan peninjauan kode; pastikan Anda memberikan waktu yang cukup untuk hal tersebut
Beberapa rekomendasi telah diedit dan diringkas agar lebih jelas.
Seperti dalam program 2021, sebagian besar penulis teknis di Season of Docs 2022 mengajukan permohonan langsung ke organisasi tempat mereka bekerja.
Masalah umum dalam bekerja sama dengan penulis teknis
Lebih sedikit project yang melaporkan masalah dalam bekerja sama dengan penulis teknis mereka di program 2022. Penulis teknis yang tidak dapat menyelesaikan program adalah masalah terbesar, karena sakit, mengambil pekerjaan penuh waktu, atau tidak dapat memenuhi komitmen waktu.
Satu project melaporkan bahwa project dokumentasi mereka bergantung pada pekerjaan yang dilakukan sebagai bagian dari Google Summer of Code, dan bahwa dependensi tersebut sulit dikelola. Project lain mengalami kesulitan saat hardware yang dibutuhkan penulis teknis untuk didokumentasikan disita oleh Kementerian Pertahanan di negara penulis dan tidak dapat diimpor.
Survei tindak lanjut
Tiga survei tindak lanjut akan dikirimkan kepada peserta 2022 pada bulan Mei, Agustus, dan November 2023. Kami akan memperbarui bagian ini dengan hasil yang diterima.
Pertanyaan mendatang
Seperti biasa, semakin banyak kita mempelajari dokumentasi di open source, semakin banyak yang ingin kita pelajari.
Pada musim mendatang, kami berharap untuk:
- Mengumpulkan lebih banyak metadata project untuk mencari korelasi antara usia project, ukuran komunitas, atau bahasa dan kebutuhan dokumentasi
- Menganalisis project dokumentasi untuk melihat apakah project tersebut dapat digeneralisasi menjadi template yang dapat dibagikan
- Mengembangkan rubrik untuk mewawancarai penulis teknis dalam project open source
Meskipun ada banyak pertanyaan yang ingin kami selidiki, kami juga ingin menghargai waktu admin dan pengelola project open source yang berpartisipasi dalam Season of Docs. Prioritas utama program ini adalah mendukung project dalam memecahkan masalah mereka dengan dokumentasi.