Fase saat ini:
Pengembangan dokumentasi. Lihat
linimasa.
Season Dokumen adalah program keberlanjutan yang dikelola oleh Google Open Source Programs Office. Tujuan dari Season Dokumen adalah untuk:
- Memberikan dukungan untuk proyek {i>open source<i} untuk memecahkan masalah proyek melalui dokumentasi
- Memberikan peluang kepada penulis teknis untuk mendapatkan pengalaman di open source
- Meningkatkan kesadaran akan open source, dokumentasi, dan penulisan teknis
- Mengumpulkan dan membagikan informasi tentang metrik yang efektif dalam dokumentasi open source
Informasi selengkapnya tentang Season Dokumen tersedia di situs program.
Ringkasan program 2022
Cara kerja Season Dokumen
Pada Musim Dokumen, organisasi mengajukan permohonan dengan mengirimkan proposal proyek. Proposal proyek mencakup:
- Informasi tentang organisasi
- Deskripsi masalah yang dihadapi proyek
- Bagaimana proyek akan menggunakan dokumentasi untuk membantu memecahkan masalah mereka
- Bagaimana proyek akan mengukur efektivitas dokumentasi mereka (metrik)
- {i>Timeline<i} untuk pekerjaan
- Anggaran proyek
- Informasi tambahan apa pun, seperti pengalaman organisasi dalam program serupa, atau apa pun yang dapat membantu administrator Season of Docs memahami proyek dan masalah mereka
Setelah diterima di program ini, organisasi merekrut dan mempekerjakan penulis teknis mereka sendiri secara langsung. Season Dokumen 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 Musim situs Dokumen, dan pembayaran dapat dilihat di Musim akun Open Collective Dokumen.
Organisasi dianggap telah berhasil menyelesaikan program ini ketika mereka mengirimkan laporan studi kasus. Organisasi juga diminta untuk menyelesaikan evaluasi bulanan selama program dan tiga survei tindak lanjut tiga bulanan selama setahun setelah penyelesaian program.
Sorotan 2022
“Setelah dokumen baru dirilis, kunjungan harian ke Casbin dan Casdoor meningkat hampir dua kali lipat, dan rasio pantulan turun sekitar 30%.”—Casbin
“Hasil yang menyenangkan dari project ini telah menyaksikan [penulis teknis kami] berkembang menjadi peran kepemimpinan di komunitas kami. Kedua kontributor kini memimpin pertemuan kelompok kerja dan komunitas, serta berkontribusi terhadap desain dan pemeliharaan project kami.” —moja-global
“[GSoD] membantu kami merekrut dua penulis teknis berbakat yang sangat sulit dalam dunia reguler, yang terus menjadi kontributor OS aktif OpenMined, dan memiliki pengalaman kerja yang luar biasa dengan kami.” —OpenMined
“Selain itu, panduan baru ini jauh lebih mudah bagi pemula dalam hal spektrometri massa komputasi. Untuk menggambarkan poin ini: hibah CZI juga memberikan tunjangan bagi individu yang kurang mampu secara historis dan beberapa penerima penghargaan telah menggunakan panduan baru OpenMS untuk memulai periode magang enam minggu mereka dan telah memberikan ulasan positif terhadap panduan baru ini.” —OpenMS
Data Ringkasan 2022
Pada tahun 2022, program Season of Docs menerima 31 proyek dari 67 aplikasi, dan 30 proyek berhasil menyelesaikan program ini. Dari 31 organisasi yang diterima, 17 organisasi merupakan pelamar berulang.
31 proyek yang diterima merekrut 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 pendaftaran
- 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 Dokumen 2022 mewakili berbagai macam project open source. Kelompok 2022 mencakup:
- Alat pengembangan, seperti AsyncAPI dan SpyderIDE
- Bahasa pemrograman dan framework, seperti Julia, LFortran, R, dan p5.js
- Proyek 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 memang meminta proyek untuk menunjukkan lisensi {i>open source <i}mana yang mereka gunakan.
Tentang proyek dokumentasi
Masalah dokumentasi
Masalah utama yang ingin diselesaikan oleh organisasi melalui dokumentasi dalam program 2022 mencakup:
Perhatikan bahwa organisasi dapat melaporkan beberapa masalah dokumentasi. Untuk lebih spesifik, lihat halaman hasil Season Dokumen 2022, yang ditautkan ke proposal project asli dan studi kasus lengkap untuk setiap organisasi.
Jenis dokumentasi yang dibuat
Dokumentasi petunjuk adalah jenis dokumentasi yang paling sering disebutkan dalam studi kasus tahun 2022.
Jenis dokumentasi lain yang disebutkan dalam studi kasus termasuk:
- Panduan memulai
- Glosarium
- FAQ
- Basis pengetahuan
- Komponen
- Konten blog/media sosial
- Panduan pengelola
Beberapa kategori ini tidak jelas dan satu proyek dokumentasi dapat berisi beberapa jenis atau fitur dokumentasi.
Untuk lebih spesifik, lihat halaman hasil Season Dokumen 2022, yang ditautkan 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 meminta hibah terendah (antara $5 ribu-$7 ribu).
Metrik
Proyek yang diuraikan dalam studi kasus mereka, metrik yang mereka gunakan untuk mengukur keberhasilan proyek dokumentasi mereka.
Metrik teratas yang diusulkan adalah:
Metrik lain yang diusulkan termasuk:
- Kontribusi/permintaan pull dokumentasi lainnya
- Lebih banyak masukan langsung tentang halaman dokumentasi
- Waktu yang dihabiskan di halaman
- Masalah yang dilaporkan (sebagai proxy untuk digunakan)
- Peserta dalam forum
- Jumlah partner/sukarelawan/integrasi
- Pengurangan rasio pantulan
- Peningkatan kesadaran di masyarakat.
Karena waktu yang singkat antara menyelesaikan proyek penulisan teknis dan mengirimkan studi kasus, sebagian besar kelompok tahun 2022 tidak dapat mengumpulkan cukup data pada saat mengirimkan studi kasus mereka untuk menentukan apakah metrik awal mereka telah terpenuhi atau tidak.
Setelah menerima jawaban atas survei lanjutan pada tahun 2023, kami akan memperbarui laporan ini untuk menambahkan informasi tentang project mana yang telah mencapai metriknya atau merevisi metriknya.
Untuk lebih spesifik, lihat halaman hasil Season Dokumen 2022, yang ditautkan ke proposal project asli dan studi kasus lengkap untuk setiap organisasi.
Bekerja sama dengan penulis teknis
Dalam program Season of Docs, proyek diharapkan merekrut, mewawancarai, mempekerjakan, dan membayar penulis teknis secara langsung. Penulis teknis dapat menambahkan dirinya sendiri 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 proyek open source
Project diminta untuk membagikan praktik terbaik dalam merekrut, merekrut, dan bekerja dengan penulis teknis. Rekomendasi teratas adalah:
Perekrutan
- Mewawancarai lebih sedikit kandidat, dan menggunakan sesi latihan langsung, bukan hanya meninjau CV
- Nilai keterampilan komunikasi tertulis dan lisan daripada kemahiran dalam bahasa atau peralatan proyek
- Ajukan pertanyaan langsung tentang bagaimana penulis teknis akan memperoleh pengetahuan domain apa pun yang diperlukan untuk bekerja dengan proyek Anda
- Seseorang yang antusias dengan misi proyek Anda dan memiliki nilai-nilai {i>open source<i} inti yang sama-sama akan tetap termotivasi selama proyek berlangsung
- Bersikaplah terbuka bagi pelamar dari seluruh dunia, karena beragam sudut pandang dan latar belakang akan membantu proyek Anda—tetapi perlu diingat bahwa memiliki penulis dan mentor yang berada di terlalu banyak zona waktu yang bertentangan dapat memerlukan banyak upaya ekstra untuk menjaga komunikasi yang baik
Lowongan
- Gunakan kontrak yang dengan jelas menguraikan hasil kerja, jadwal pembayaran, dan komitmen waktu tertentu
- Jika proyek Anda memiliki banyak hal yang tidak diketahui, sertakan {i>milestone<i} untuk penemuan atau penelitian yang terpisah dari pembuatan dokumentasi
Koordinasi dan komunikasi
- Simpan keputusan rekaman log rapat untuk memudahkan semua orang yang mengerjakan proyek untuk memahami konteks dan langkah selanjutnya
- Sampaikan dengan jelas komunikasi apa yang diharapkan dan seberapa sering, apakah itu panggilan mingguan, email harian, atau pembaruan status di saluran chat
- Bersikap responsif dan berikan masukan yang jelas yang mencakup 'mengapa' dan bukan hanya 'apa'
- Menghubungkan penulis teknis dengan komunitas luas untuk memberikan konteks dan menyosialisasikan karya mereka
Proses dan alat
- Buat proses dokumentasi yang akan berlaku setelah program Dokumen, dan bahwa seluruh komunitas dapat berkontribusi
- Peninjauan dokumentasi akan memakan waktu setidaknya lama dan sama intensifnya dengan peninjauan kode; pastikan Anda memberikan cukup waktu untuk itu
Beberapa rekomendasi telah diedit dan diringkas agar lebih jelas.
Seperti dalam program 2021, sebagian besar penulis teknis di Season of Docs 2022 langsung diterapkan ke organisasi yang bekerja sama dengan mereka.
Masalah umum dalam bekerja dengan penulis teknis
Lebih sedikit project melaporkan masalah terkait kerja sama dengan penulis teknis dalam program 2022. Penulis teknis yang tidak dapat menyelesaikan program ini adalah masalah terbesar, karena penyakit, mengambil pekerjaan purnawaktu, atau tidak dapat memenuhi komitmen waktu.
Salah satu project melaporkan bahwa project dokumentasinya bergantung pada pekerjaan yang sedang dilakukan sebagai bagian dari Google Summer of Code, dan bahwa dependensi tersebut sulit dikelola. Proyek lain mengalami kesulitan ketika perangkat keras yang diperlukan penulis teknis untuk mendokumentasikannya disita oleh Kementerian Pertahanan di negara penulis dan tidak dapat diimpor.
Survei lanjutan
Tiga survei lanjutan akan dikirimkan kepada peserta tahun 2022 pada Mei, Agustus, dan November 2023. Kami akan memperbarui hasil pada bagian ini setelah diterima.
Pertanyaan mendatang
Seperti biasa, semakin banyak kita belajar tentang dokumentasi di {i>open source<i}, semakin banyak hal yang ingin kita pelajari.
Pada musim mendatang, kami berharap dapat:
- Mengumpulkan lebih banyak metadata proyek untuk mencari korelasi antara usia proyek, ukuran komunitas, atau kebutuhan bahasa dan dokumentasi
- Menganalisis proyek dokumentasi untuk melihat apakah proyek tersebut dapat digeneralisasi menjadi {i>template<i} yang dapat dibagikan
- Mengembangkan rubrik untuk mewawancarai penulis teknis dalam proyek open source
Meskipun ada banyak pertanyaan yang ingin kami selidiki, kami juga ingin menghargai waktu dari admin dan pemelihara project open source yang berpartisipasi dalam Season Dokumen. Prioritas utama program ini adalah mendukung proyek dalam memecahkan masalah mereka dengan dokumentasi.