Season of Docs adalah program keberlanjutan yang dikelola oleh Google Open Source Programs Office. Sasaran Season of Docs adalah untuk:
- Memberikan dukungan untuk project open source guna memecahkan masalah project dengan dokumentasi
- Memberi penulis teknis kesempatan untuk mendapatkan pengalaman dalam 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
Dalam Season of Docs, organisasi mendaftar dengan mengirimkan proposal project. Proposal project mencakup:
- Informasi tentang organisasi
- Deskripsi masalah yang dihadapi project
- Cara project akan menggunakan dokumentasi untuk membantu memecahkan masalahnya
- Cara project akan mengukur efektivitas dokumentasi mereka (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 masalah mereka
Setelah diterima dalam program ini, 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 berlangsung dan tiga survei tindak lanjut kuartalan selama setahun setelah program selesai.
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 pemimpin di komunitas kami. Kedua kontributor tersebut kini memimpin rapat komunitas dan kelompok kerja, serta berkontribusi pada desain dan pemeliharaan project kami.” —moja-global
“[GSoD] membantu kami merekrut dua penulis teknis berbakat yang sangat sulit dalam penyiapan reguler, yang terus menjadi kontributor OS aktif untuk OpenMined, dan kami memiliki pengalaman kerja yang luar biasa dengan mereka.” —OpenMined
“Selain itu, manual baru ini jauh lebih mudah bagi pemula dalam spektrometri massa komputasi. Untuk menggambarkan hal ini: hibah CZI juga memberikan tunjangan bagi individu yang secara historis kurang beruntung dan beberapa penerima hibah telah menggunakan manual OpenMS baru untuk memulai periode magang enam minggu mereka dan telah memberikan ulasan positif tentang manual 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 ini. Dari 31 organisasi yang diterima, 17 organisasi adalah pelamar berulang.
31 project yang diterima mempekerjakan 58 penulis teknis. Lebih dari 190 penulis teknis menunjukkan minat mereka untuk berpartisipasi dalam program ini 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 ini
- 90% organisasi merasa proyek dokumentasi mereka berhasil
Tentang organisasi
Organisasi yang berpartisipasi dalam Season of Docs 2022 mewakili berbagai project open source. Kohort 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 robotika, 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 ingin dipecahkan organisasi dengan dokumentasi dalam program 2022 meliputi:
Perhatikan bahwa organisasi dapat melaporkan beberapa masalah dokumentasi. Untuk mengetahui detail selengkapnya, lihat halaman hasil Season of Docs 2022, yang tertaut ke proposal project asli dan studi kasus lengkap untuk setiap organisasi.
Jenis dokumentasi yang dibuat
Dokumentasi cara adalah jenis dokumentasi yang paling sering disebutkan dalam studi kasus 2022.
Jenis dokumentasi lain yang disebutkan dalam studi kasus meliputi:
- Panduan memulai
- Glosarium
- FAQ
- Pusat informasi
- 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, yang tertaut 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 yang diuraikan dalam studi kasus mereka menjelaskan metrik yang digunakan untuk mengukur keberhasilan project dokumentasi mereka.
Metrik teratas yang diusulkan adalah:
Metrik lain yang diusulkan mencakup:
- Pull request/kontribusi dokumentasi lainnya
- Masukan yang lebih langsung di halaman dokumentasi
- Waktu yang dihabiskan di halaman
- Masalah yang diangkat (sebagai proxy untuk penggunaan)
- Peserta dalam forum
- Jumlah partner/relawan/integrasi
- Mengurangi rasio pantulan
- Meningkatkan awareness di komunitas.
Karena jangka waktu yang singkat antara menyelesaikan project penulisan teknis dan mengirimkan studi kasus, sebagian besar peserta angkatan 2022 belum dapat mengumpulkan data yang cukup pada saat mengirimkan studi kasus untuk menentukan apakah metrik awal mereka telah terpenuhi atau belum.
Setelah menerima jawaban survei lanjutan 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, yang tertaut 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 repositori 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 teratas adalah:
Perekrutan
- Wawancarai lebih sedikit kandidat, dan gunakan sesi latihan langsung, bukan hanya meninjau CV
- Nilai keterampilan komunikasi tertulis dan lisan daripada kecakapan dalam bahasa atau alat project Anda
- Ajukan pertanyaan langsung tentang bagaimana penulis teknis akan memperoleh pengetahuan domain yang diperlukan untuk mengerjakan project Anda
- Seseorang yang antusias dengan misi project Anda dan memiliki nilai inti open source yang sama kemungkinan besar akan tetap termotivasi selama project berlangsung
- Bersikaplah terbuka terhadap pelamar dari seluruh dunia, karena keberagaman sudut pandang dan latar belakang akan membantu project Anda—tetapi perhatikan bahwa memiliki penulis dan mentor di terlalu banyak zona waktu yang bertentangan mungkin memerlukan banyak upaya ekstra untuk menjaga komunikasi yang baik
Lowongan
- Gunakan kontrak yang menjelaskan hasil kerja, jadwal pembayaran, dan komitmen waktu tertentu dengan jelas
- Jika project Anda memiliki banyak hal yang tidak diketahui, sertakan pencapaian untuk penemuan atau riset yang terpisah dari pembuatan dokumentasi
Koordinasi dan komunikasi
- Simpan 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 seringnya, baik itu panggilan telepon mingguan, email harian, atau pembaruan status di saluran chat
- Bersikaplah responsif dan berikan masukan yang jelas yang mencakup 'mengapa', bukan hanya 'apa'
- Hubungkan penulis teknis Anda dengan komunitas yang lebih luas untuk memberi mereka konteks dan mempublikasikan pekerjaan mereka
Proses dan alat
- Membuat proses dokumentasi yang akan berlangsung setelah program Season of Docs, dan yang dapat dikontribusikan oleh seluruh komunitas
- Peninjauan dokumentasi akan memakan waktu setidaknya sama lama dan sama intensifnya dengan peninjauan kode; pastikan Anda menyediakan waktu yang cukup untuk peninjauan tersebut
Beberapa rekomendasi telah diedit dan diringkas agar lebih jelas.
Seperti pada program tahun 2021, sebagian besar penulis teknis di Season of Docs 2022 melamar langsung ke organisasi tempat mereka bekerja.
Masalah umum dalam bekerja sama dengan penulis teknis
Lebih sedikit project yang melaporkan masalah saat bekerja sama dengan penulis teknis mereka dalam program 2022. Penulis teknis yang tidak dapat menyelesaikan program adalah masalah terbesar, karena sakit, memiliki 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 perlu didokumentasikan oleh penulis teknis mereka disita oleh Kementerian Pertahanan di negara penulis dan tidak dapat diimpor.
Survei lanjutan
Tiga survei lanjutan akan dikirim kepada peserta 2022 pada Mei, Agustus, dan November 2023. Kami akan memperbarui bagian ini dengan hasil yang diterima.
Pertanyaan mendatang
Seperti biasa, semakin banyak kita mempelajari dokumentasi dalam open source, semakin banyak hal yang ingin kita pelajari.
Pada musim mendatang, kami berharap dapat:
- Mengumpulkan lebih banyak metadata project untuk mencari korelasi antara usia project, ukuran komunitas, atau kebutuhan bahasa dan 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.