Laporan Studi Kasus 2021

Fase saat ini:
Program Season of Docs 2021 berakhir pada 14 Desember 2021. Lihat linimasa.

Catatan: Laporan ini merangkum data dari aplikasi program asli dan dari studi kasus akhir organisasi. Studi kasus lengkapnya ditautkan dari halaman hasil Season of Docs 2021.

Tentang Season of Docs

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 peluang 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 Dokumen tersedia di situs program.

Ringkasan program 2021

Perubahan program 2021

Pada tahun 2019 dan 2020, organisasi dan penulis teknis masing-masing mendaftar ke program Season Dokumen secara terpisah, dan penulis teknis dicocokkan dengan organisasi berdasarkan administrator program Season Dokumen. Organisasi menyediakan mentor untuk bekerja sama dengan penulis teknis, yang menerima tunjangan untuk pekerjaan mereka berdasarkan lokasi mereka. Program ini mengukur apakah penulis teknis, mentor, dan admin organisasi puas dengan partisipasi mereka dalam program, tetapi tidak mengukur hasil dokumentasi.

Pada tahun 2021, tim Season of Docs melakukan perubahan signifikan pada program, mengalihkan fokus untuk mengukur hasil dokumentasi dan memungkinkan lebih banyak fleksibilitas bagi organisasi dan penulis teknis.

  • Organisasi yang mengajukan permohonan dengan proposal proyek, termasuk anggaran dan metrik yang diusulkan
  • Penulis teknis tidak lagi mendaftar melalui Google untuk dicocokkan dengan organisasi, tetapi mendaftar langsung ke organisasi yang diterima
  • Organisasi yang diterima menerima hibah melalui Open Collective, yang mereka gunakan untuk membayar penulis teknis
  • Kompensasi untuk penulis teknis ditetapkan oleh organisasi
  • Organisasi mengirimkan evaluasi akhir dan studi kasus serta menjawab survei tindak lanjut

Temuan umum 2021

Organisasi

  • Perubahan pada program 2021 menyebabkan lebih sedikit organisasi yang mendaftar (kami melihat 30% lebih sedikit organisasi yang mendaftar pada tahun 2021 dibandingkan tahun 2020), tetapi admin organisasi 2021 sedikit lebih puas dengan program ini dibandingkan admin 2020 (93% v 91%)

Soal, doctype, dan metrik

  • Sebagian besar project berfokus pada pembuatan dokumentasi untuk mengurangi beban pengelola (melalui pengurangan masalah/pertanyaan) dan/atau meningkatkan partisipasi project (baik oleh pengguna project maupun kontributor).
    • 50% organisasi yang diterima membuat konten Tutorial atau Petunjuk.
    • Lebih dari 50% organisasi yang diterima menganggap dokumentasi mereka saat ini kurang, tidak teratur, atau ketinggalan zaman.
  • Project umumnya ingin mengukur efektivitas dokumentasi mereka melalui interaksi, terutama lebih sedikit masalah yang diangkat dan lebih banyak pengunjung ke dokumen serta partisipasi dalam project.
  • Per November 2022, dengan 25 dari 30 project yang merespons:
    • 18 project menyatakan bahwa mereka telah memenuhi metrik awal
    • 5 project telah memenuhi metrik yang direvisi
    • 2 project mengatakan masih terlalu dini untuk mengetahuinya

Partisipasi program

  • Merekrut, merekrut, dan membayar penulis teknis adalah bagian tersulit dari program ini bagi administrator organisasi.
  • Per November 2022, dengan 24 dari 30 organisasi yang merespons:
    • 18 organisasi masih bekerja sama dengan penulis teknis Season of Docs mereka (baik sebagai kontributor berkelanjutan maupun referensi untuk menjawab pertanyaan)
      • 4 organisasi bekerja sama dengan penulis teknis Season of Docs mereka dalam peran berbayar

Sorotan 2021

  • Beberapa project menunjukkan bahwa penulis teknis mereka bermaksud untuk terus mengerjakan project mereka setelah program Season of Docs berakhir
  • Metanorma menerima begitu banyak lamaran dari penulis teknis yang memenuhi syarat sehingga mereka menemukan dana yang cocok untuk mempekerjakan penulis tambahan yang akan bekerja sama dengan penulis yang didukung Season of Docs selama program berlangsung
  • Moja Global mendapati bahwa komunitas sangat aktif dalam mengerjakan dokumentasi dan membuat Documentation Working Group baru untuk memungkinkan lebih banyak kontributor berpartisipasi dalam dokumentasi proyek

Data ringkasan 2021

Pada tahun 2021, 82 organisasi mengajukan permohonan dan 30 organisasi open source diterima dalam program ini. (Lihat Panduan Membuat Aplikasi untuk mengetahui kriteria pemilihan.) Daftar lengkap organisasi yang berpartisipasi dapat ditemukan di situs Season of Docs. Semua 30 organisasi yang diterima mengirimkan laporan studi kasus akhir untuk menyelesaikan partisipasi mereka dalam program 2021.

Tentang organisasi

Organisasi yang berpartisipasi dalam Season of Docs 2021 mewakili berbagai project open source. Kohort 2021 mencakup:

  • Proyek bahasa besar seperti Julia, Perl, dan R
  • Project di bidang pendidikan, iklim, fintech, layanan kesehatan, layanan perpustakaan, machine learning, spektrometri massa, kontrak publik, dan robotika
  • Project yang berfokus pada developer, termasuk alat chaos engineering, fuzzer, SDK chatbot, pipeline analisis komposisi software, alat pemantauan performa, dan alat pemrograman visual
  • Project dokumentasi untuk alat dokumentasi, seperti Redocly dan Metanorma

Project ekosistem Python adalah subkategori terbesar. Kohort 2021 mencakup ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite, dan SymPy.

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.

Diagram batang yang menunjukkan jumlah project yang menggunakan setiap lisensi OSS: Apache 2.0: sepuluh program; BSD 3-klausul: lima program; MIT: lima program; GPL 2.0: 4 program; LGPL 2.1: 4 program; Lisensi Publik Mozilla 2.0: 3 program; Artistic, Boost, dan BSD 2-klausul: masing-masing satu program

Masalah dokumentasi yang diuraikan oleh organisasi 2021 adalah masalah yang sangat umum dalam project open source dan dokumentasi teknis secara umum.

Masalah utama yang ingin diselesaikan organisasi dalam program 2021 meliputi:

Grafik batang menunjukkan masalah yang dilaporkan oleh organisasi: Kurangnya dokumentasi untuk kasus penggunaan tertentu dari aspek proyek: 14 proyek; Dokumentasi tidak terorganisir: 14 proyek; Dokumentasi sudah usang: 6 proyek; Dokumentasi tidak konsisten: 3 proyek; Dokumentasi perlu dikonversi ke alat, platform, atau format yang berbeda: 2 proyek

Perhatikan bahwa organisasi dapat melaporkan beberapa masalah dokumentasi. Untuk mengetahui detail selengkapnya, lihat halaman hasil Season of Docs 2021, yang tertaut ke studi kasus lengkap untuk setiap organisasi.

Jenis dokumentasi yang dibuat

Tutorial adalah jenis dokumentasi yang paling sering disebutkan dalam studi kasus 2021.

Diagram batang yang menunjukkan jenis dokumentasi yang dibuat: Tutorial: 9 project; Cara: 6 project; Memulai: 3 project; Contoh: 3 project; Referensi: 3 project; Dokumen API, Video, Mulai Cepat, Template, Halaman landing: masing-masing 2 project

Jenis dokumentasi lain yang disebutkan dalam studi kasus mencakup Pipeline dokumen sebagai kode, Diagram, Glosarium, Panduan Gaya, FAQ, Internasionalisasi, Codelab, Model konten, Modul, Dokumentasi konsep, Pesan error, Riset pengguna, Readme, Knowledgebase.

Beberapa kategori ini tidak jelas dan satu project dokumentasi dapat berisi beberapa jenis atau fitur dokumentasi.

Beberapa project secara khusus dirujuk menggunakan framework Diátaxis sebagai panduan untuk merencanakan jenis dokumentasi mereka.

Untuk mengetahui detail selengkapnya, lihat halaman hasil Season of Docs 2021, yang tertaut ke studi kasus lengkap untuk setiap organisasi.

Anggaran

Pada tahun 2021, permintaan anggaran rata-rata adalah $10.200 dan mediannya adalah $10.000. Hanya tiga organisasi yang meminta dan menerima hibah maksimum ($15 ribu), dan tiga organisasi lainnya meminta hibah serendah mungkin ($5 ribu).

Metrik

Project yang diuraikan dalam studi kasus mereka menjelaskan metrik yang digunakan untuk mengukur keberhasilan project dokumentasi mereka.

Metrik teratas yang diusulkan adalah:

Diagram batang yang menunjukkan metrik keberhasilan dokumentasi: Lebih sedikit masalah/pertanyaan project: 13 project; Lebih banyak pengunjung ke dokumentasi/penggunaan dokumen: 9 project; Lebih banyak kontributor/permintaan pull: 8 project; Lebih banyak permintaan pull/kontribusi dokumentasi: 7 project; Total jumlah dokumen yang dibuat: 5 project; Peningkatan kepuasan dokumentasi (melalui survei), Peningkatan penggunaan project, Lebih banyak masukan langsung di halaman dokumentasi: masing-masing empat project; SEO yang lebih baik: tiga project; Total persentase dokumentasi yang dikonversi dan Total persentase info target yang tercakup dalam dokumen: masing-masing dua project

Metrik lain yang diusulkan mencakup Bintang GitHub, Waktu yang dihabiskan di halaman, Konversi milis, Pengujian pengguna kualitatif, Jumlah peserta di forum, Jumlah partner/relawan/integrasi.

Karena jangka waktu yang singkat antara menyelesaikan project penulisan teknis dan mengirimkan studi kasus, sebagian besar peserta angkatan 2021 belum dapat mengumpulkan data yang cukup untuk menentukan apakah metrik awal mereka telah terpenuhi atau belum.

Untuk mengetahui detail selengkapnya, lihat halaman hasil Season of Docs 2021, yang tertaut ke studi kasus lengkap untuk setiap organisasi.

Bekerja sama dengan penulis teknis

Perubahan terbesar pada program Season of Docs tahun 2021 terkait cara project bekerja dengan penulis teknis. Pada musim sebelumnya, penulis teknis melamar langsung ke Google dan dicocokkan oleh administrator program dengan project, serta dibayarkan tunjangan tetap langsung dari Google.

Pada tahun 2021, penulis teknis melamar langsung ke project dan project menetapkan anggaran untuk kompensasi penulis teknis, dengan pembayaran dilakukan melalui dana Open Collective Season of Docs.

Sebagian besar project yang berpartisipasi dalam program 2021 memiliki sedikit atau tidak ada pengalaman dalam merekrut atau mempekerjakan penulis teknis, dan banyak project menyebut bagian proses ini sebagai bagian yang memerlukan lebih banyak dukungan. Sebagai respons atas masukan ini, tim Season of Docs menambahkan dokumentasi untuk membuat perjanjian penulis teknis ke panduan program.

Rekomendasi perekrutan

Project diminta untuk membuat rekomendasi bagi project lain yang tertarik untuk berpartisipasi dalam Season Dokumen. Rekomendasi perekrutan teratas adalah:

  • Bagikan materi perekrutan untuk penulis teknis sedini mungkin, bahkan sebelum Anda diterima dalam program. Mintalah komunitas Anda untuk menyarankan kandidat yang mungkin.
  • Membagikan secara luas di luar saluran project. Gunakan bahasa inklusif dan langsung dorong kandidat dari latar belakang yang kurang terwakili untuk mendaftar.
  • Pahami alat yang penting untuk proses pembuatan dokumentasi Anda dan rekrut penulis teknis yang berpengalaman menggunakan alat tersebut.
  • Buat ekspektasi yang jelas bagi penulis teknis tentang hasil dan pencapaian, saluran komunikasi dan check-in, serta proses dan waktu pembayaran.
  • Pertimbangkan untuk berinvestasi pada anggota komunitas dan membantu mereka berkembang sebagai penulis teknis dengan menggunakan penulis teknis Season of Docs untuk memberikan bimbingan dan pembinaan.
  • Alokasikan lebih banyak waktu dari yang Anda harapkan untuk orientasi penulis teknis dan menjawab pertanyaan dan memberikan dukungan selama program, terutama jika penulis teknis tidak memiliki pengalaman sebelumnya di domain proyek Anda.
  • Dokumentasikan proses perekrutan, perekrutan, dan orientasi Anda untuk digunakan pada project mendatang.

Grafik batang yang menunjukkan sumber kandidat penulis teknis: Diterapkan langsung ke program: 7; SoD GitHub atau peserta SoD sebelumnya: 4; Menulis Docs Slack atau Anggota komunitas: 3 masing-masing; Diterapkan melalui situs pekerjaan (Upwork, LinkedIn) atau Google Summer of Code atau alumni Code-In: masing-masing 2

(Catatan: tidak semua project menunjukkan dalam studi kasusnya tempat mereka merekrut kandidat penulis teknis.)

Masalah umum dalam bekerja sama dengan penulis teknis

Diagram batang yang menunjukkan masalah penulis teknis: TW keluar: 8 project; Masalah komunikasi: 6 project; Orientasi TW: 4 project; Perekrutan TW; Perekrutan atau pembayaran; Penyiapan alat project: masing-masing 3 project

Penulis teknis di beberapa project harus berhenti karena COVID atau penyakit lainnya, atau karena tanggung jawab keluarga terkait pandemi. Beberapa project melaporkan masalah komunikasi yang melibatkan ketidakcocokan zona waktu atau masalah konektivitas internet.

Project menemukan bahwa mereka meremehkan kesulitan yang terlibat dalam orientasi ke dalam komunitas mereka atau dalam menyiapkan toolchain dokumen project mereka.

Beberapa proyek mengalami keterlambatan pembayaran penulis teknis karena masalah perbankan pada Open Collective atau karena negara asal penulis memiliki batasan pembayaran.

Dokumentasi program terkait biaya Open Collective tidak jelas: Google menanggung biaya transaksi Open Collective untuk transfer dana awal ke project, tetapi tidak menanggung biaya transaksi yang dikenakan oleh beberapa saluran pembayaran lainnya (seperti biaya konversi mata uang). Kami akan berupaya untuk memperjelas hal ini dalam dokumentasi untuk program mendatang.

Survei lanjutan

Sebagai bagian dari program Season Dokumen, proyek diminta untuk berpartisipasi dalam survei tindak lanjut. Tiga survei dikirim pada Mei, Agustus, dan November 2022.

Diagram batang yang menunjukkan jumlah respons terhadap survei lanjutan: Survei Mei: 13 respons; Survei Agustus: 21 respons; Survei November: 12 respons

Survei lanjutan meminta project untuk mengonfirmasi bahwa link proposal dan studi kasus mereka masih aktif. Survei ini juga mencakup pertanyaan tentang keberhasilan project mereka (sebagaimana ditentukan oleh metrik yang mereka tetapkan dalam studi kasus) serta partisipasi dan kompensasi berkelanjutan dari penulis teknis project:

  1. Apakah Anda masih bekerja sama dengan penulis teknis Season of Docs?

Diagram batang yang menunjukkan partisipasi berkelanjutan oleh penulis teknis, per survei: pada bulan Mei, 6 project memiliki penulis teknis yang berpartisipasi atau menjawab pertanyaan; 1 project tidak memiliki keterlibatan penulis teknis yang berkelanjutan. Pada bulan Agustus, 11 project memiliki partisipasi penulis teknis yang sedang berlangsung; tujuh project tidak memiliki partisipasi penulis teknis yang sedang berlangsung, dan 3 project memiliki penulis teknis yang menjawab pertanyaan. Pada bulan November, 5 proyek melaporkan keterlibatan penulis teknis yang sedang berlangsung; 3 proyek melaporkan tidak ada keterlibatan penulis teknis yang sedang berlangsung; dan 4 proyek melaporkan penulis teknis yang menjawab pertanyaan.

  1. Jika penulis teknis Anda masih mengerjakan project Anda, apakah ia menerima kompensasi?

Diagram batang yang menampilkan jumlah project yang melaporkan kompensasi project mereka untuk penulis teknis dalam setiap survei. Pada bulan Mei, 5 proyek melaporkan bahwa penulis teknis mereka dibayar untuk pekerjaan yang sedang berlangsung; 4 proyek melaporkan bahwa penulis teknis mereka tidak dibayar. Pada bulan Agustus, 4 project melaporkan bahwa mereka membayar penulis teknis dan 7 project melaporkan bahwa penulis teknis mereka tidak dibayar. Pada bulan November, dua proyek melaporkan bahwa mereka membayar penulis teknis, dan 5 proyek melaporkan bahwa penulis teknis mereka tidak dibayar.

  1. Pada tahap ini, apakah Anda merasa project dokumentasi Anda berhasil?

Diagram batang yang menunjukkan jumlah project yang melaporkan keberhasilan berdasarkan metrik dalam setiap survei. Pada bulan Mei, 6 project melaporkan bahwa metrik mereka telah terpenuhi; 6 project mengatakan bahwa masih terlalu dini untuk mengetahuinya, dan 2 project telah memenuhi metrik yang disesuaikan. Pada bulan Agustus, 16 project melaporkan bahwa metrik telah terpenuhi; 3 project melaporkan bahwa metrik yang disesuaikan telah terpenuhi; dan 2 project melaporkan bahwa masih terlalu dini untuk mengetahuinya. Pada bulan November, 9 project melaporkan bahwa metrik telah terpenuhi; 3 project melaporkan bahwa metrik yang disesuaikan telah terpenuhi, dan tidak ada project yang melaporkan bahwa masih terlalu dini untuk mengetahuinya.

Pertanyaan mendatang

Seperti biasa, semakin banyak kita belajar tentang dokumentasi di {i>open source<i}, semakin banyak yang ingin kita pelajari. Pada musim mendatang, kami berharap dapat mempelajari:

  • Apakah domain proyek berkorelasi dengan pilihan doctype atau pilihan metrik
  • Praktik perekrutan dan orientasi penulis teknis mana yang paling efektif untuk penyelesaian project dan retensi penulis teknis
  • Linimasa yang wajar untuk mengukur keefektifan dokumentasi

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 proyek dalam memecahkan masalah mereka dengan dokumentasi.