Laporan Studi Kasus 2021

Fase saat ini:
Program Dokumen Musim 2021 selesai pada 14 Desember 2021. Lihat linimasa.

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

Tentang Season Dokumen

Season Dokumen adalah program keberlanjutan yang dikelola oleh Kantor Program Open Source Google. Tujuan Season Dokumen adalah untuk:

  • Memberikan dukungan untuk proyek {i>open source<i} untuk memecahkan masalah proyek dengan dokumentasi
  • Memberi penulis teknis peluang untuk mendapatkan pengalaman di bidang open source
  • Meningkatkan awareness terkait 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, masing-masing organisasi dan penulis teknis mendaftar ke program Season of Docs secara terpisah, dan penulis teknis dicocokkan dengan organisasi oleh administrator program Season of Docs. Organisasi menyediakan mentor untuk bekerja 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 membuat perubahan signifikan pada program ini, yang mengalihkan fokus ke pengukuran hasil dokumentasi dan memberikan fleksibilitas yang lebih besar bagi organisasi dan penulis teknis.

  • Organisasi yang diterapkan dengan proposal proyek, termasuk anggaran dan metrik yang diusulkan
  • Penulis teknis tidak lagi mendaftar melalui Google untuk dicocokkan dengan organisasi, tetapi langsung diterapkan 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 tahun 2021

Organisasi

  • Perubahan dalam program 2021 menyebabkan lebih sedikit organisasi yang mendaftar (kami melihat 30% lebih sedikit organisasi yang mendaftar pada tahun 2021 vs. 2020), tetapi admin organisasi tahun 2021 sedikit lebih puas dengan program tersebut daripada admin tahun 2020 (93% v 91%)

Masalah, doctypes, dan metrik

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

Partisipasi program

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

Sorotan 2021

  • Beberapa proyek menunjukkan bahwa penulis teknis mereka bermaksud untuk terus mengerjakan proyek mereka setelah berakhirnya program Musim Dokumen
  • Metanorma meminta banyak penulis teknis berkualitas untuk mendaftar sehingga mereka menemukan dana yang sesuai untuk mempekerjakan penulis tambahan guna bekerja bersama penulis yang didukung Musim Dokumen selama program berlangsung
  • Moja Global mendapati bahwa komunitas sangat terlibat dalam dokumentasi dan membentuk Kelompok Kerja Dokumentasi baru agar lebih banyak kontributor dapat berpartisipasi dalam dokumentasi proyek

Data ringkasan 2021

Pada tahun 2021, 82 organisasi telah mendaftar dan 30 organisasi open source diterima untuk program ini. (Lihat panduan Membuat Permohonan untuk kriteria pemilihan.) Daftar lengkap organisasi yang berpartisipasi dapat ditemukan di situs Season of Dokumen. Sebanyak 30 organisasi yang diterima telah mengirimkan laporan studi kasus akhir untuk menyelesaikan partisipasi mereka dalam program 2021.

Tentang organisasi

Organisasi yang berpartisipasi dalam Season Dokumen 2021 mewakili beragam proyek open source. Kelompok tahun 2021 mencakup:

  • Project bahasa besar seperti Julia, Perl, dan R
  • Project di bidang pendidikan, iklim, teknologi finansial (fintech), layanan kesehatan, layanan perpustakaan, machine learning, spektrometri massa, kontrak publik, dan robotika
  • Project yang berfokus pada developer, termasuk alat rekayasa kekacauan, 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. Kelompok 2021 termasuk 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 proyek untuk menunjukkan lisensi {i>open source<i} mana yang mereka gunakan.

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

Masalah dokumentasi yang dijelaskan oleh organisasi tahun 2021 adalah masalah yang sangat umum di project open source dan dokumentasi teknis secara umum.

Masalah utama yang ingin dipecahkan oleh organisasi dalam program 2021 mencakup:

Grafik batang menunjukkan masalah yang dilaporkan oleh organisasi: Dokumentasi kurang untuk kasus penggunaan spesifik 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 informasi selengkapnya, lihat halaman hasil Season Dokumen 2021, yang berisi link ke studi kasus lengkap untuk setiap organisasi.

Jenis dokumentasi yang dibuat

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

Grafik batang yang menunjukkan jenis dokumentasi yang dibuat: Tutorial: 9 project; Petunjuk: 6 project; Memulai: 3 project; Contoh: 3 project; Referensi: 3 project; API Dokumen, Video, Panduan Memulai, Template, Halaman landing: 2 project masing-masing

Jenis dokumentasi lain yang disebutkan dalam studi kasus meliputi 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 kabur dan satu proyek dokumentasi dapat berisi beberapa jenis atau fitur dokumentasi.

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

Untuk mengetahui informasi selengkapnya, lihat halaman hasil Season Dokumen 2021, yang berisi link 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 yang memungkinkan ($15 ribu) dan tiga organisasi lainnya meminta hibah terendah ($5 ribu).

Metrik

Proyek yang diuraikan dalam studi kasus mereka, metrik yang mereka gunakan untuk mengukur keberhasilan proyek dokumentasi mereka.

Metrik teratas yang diusulkan adalah:

Grafik batang yang menunjukkan metrik keberhasilan dokumentasi: Lebih sedikit masalah/pertanyaan proyek: 13 proyek; Lebih banyak pengunjung untuk penggunaan dokumentasi/dokumen: 9 proyek; Lebih banyak kontributor/permintaan pull: 8 proyek; Lebih banyak permintaan pull/kontribusi dokumentasi: 7 proyek; Jumlah total dokumen yang dibuat: 5 proyek; Peningkatan kepuasan dokumentasi (melalui survei), Peningkatan penggunaan proyek, Lebih banyak masukan langsung pada halaman dokumentasi: masing-masing empat proyek; SEO yang lebih baik: tiga proyek yang dibahas;

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

Karena waktu yang singkat antara menyelesaikan proyek penulisan teknis dan mengirimkan studi kasus, sebagian besar kelompok tahun 2021 tidak dapat mengumpulkan cukup data untuk menentukan apakah metrik awal mereka telah terpenuhi atau tidak.

Untuk mengetahui informasi selengkapnya, lihat halaman hasil Season Dokumen 2021, yang berisi link ke studi kasus lengkap untuk setiap organisasi.

Bekerja sama dengan penulis teknis

Perubahan terbesar pada program Season of Docs pada 2021 melibatkan cara kerja project dengan penulis teknis. Di musim-musim sebelumnya, penulis teknis mendaftar langsung ke Google dan dikoordinasikan oleh administrator program melalui berbagai proyek, lalu menerima gaji tetap langsung dari Google.

Pada tahun 2021, penulis teknis mendaftar ke project secara langsung dan project tersebut menetapkan anggaran kompensasi penulis teknis, dengan pembayaran yang dilakukan melalui dana Kolektif Terbuka Season Dokumen.

Sebagian besar proyek yang berpartisipasi dalam program 2021 memiliki sedikit atau tidak memiliki pengalaman dalam merekrut atau mempekerjakan penulis teknis, dan banyak proyek menganggap bagian proses ini sebagai salah satu yang membutuhkan 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 rekrutmen untuk penulis teknis sesegera mungkin, bahkan sebelum Anda diterima dalam program ini. Minta komunitas Anda untuk merujukkan kandidat yang berpotensi.
  • Berbagi secara luas di luar saluran proyek. Gunakan bahasa inklusif dan secara langsung dorong kandidat dari latar belakang yang kurang terwakili untuk mendaftar.
  • Pahami alat apa yang penting untuk proses pembuatan dokumentasi Anda dan rekrut penulis teknis dengan pengalaman menggunakan alat tersebut.
  • Sampaikan ekspektasi yang jelas kepada penulis teknis tentang {i>deliverable<i} (hasil kerja) dan {i>milestone<i}, saluran komunikasi dan {i>check-in<i}, serta proses dan waktu pembayaran.
  • Pertimbangkan untuk berinvestasi pada anggota komunitas dan bantu mereka tumbuh sebagai penulis teknis dengan menggunakan penulis teknis Season of Docs untuk memberikan bimbingan dan pelatihan.
  • Siapkan lebih banyak waktu daripada yang Anda harapkan untuk orientasi penulis teknis dan menjawab pertanyaan serta memberikan dukungan selama program berlangsung, terutama jika penulis teknis tersebut tidak memiliki pengalaman sebelumnya dalam domain proyek Anda.
  • Mendokumentasikan proses perekrutan, perekrutan, dan orientasi untuk digunakan di proyek mendatang.

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

(Catatan: tidak semua proyek ditunjukkan dalam studi kasusnya di mana proyek tersebut merekrut kandidat penulis teknis.)

Masalah umum saat bekerja sama dengan penulis teknis

Grafik batang yang menunjukkan masalah penulis teknis: TW keluar: 8 proyek; Masalah komunikasi: 6 proyek; Orientasi TW: 4 proyek; Perekrutan TW; Perekrutan atau pembayaran; Pengaturan alat proyek: masing-masing 3 proyek

Penulis teknis di beberapa proyek harus mengundurkan diri karena COVID atau penyakit lain, atau karena tanggung jawab keluarga terkait pandemi. Beberapa project melaporkan masalah komunikasi yang terkait dengan ketidakcocokan zona waktu atau masalah konektivitas internet.

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

Beberapa proyek terlambat membayar penulis teknis mereka karena masalah perbankan dengan 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 awal dana ke project, tetapi bukan biaya transaksi yang diberlakukan oleh beberapa saluran pembayaran lain (seperti biaya konversi mata uang). Kami akan berupaya untuk memperjelas hal ini dalam dokumentasi untuk program-program mendatang.

Survei lanjutan

Sebagai bagian dari program Season of Docs, project diminta untuk berpartisipasi dalam survei tindak lanjut. Tiga survei telah dikirimkan pada Mei, Agustus, dan November 2022.

Grafik batang yang menunjukkan jumlah tanggapan terhadap survei tindak lanjut: Survei Mei: 13 tanggapan; Survei Agustus: 21 tanggapan; Survei November: 12 tanggapan

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

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

Grafik batang yang menunjukkan partisipasi berkelanjutan oleh penulis teknis, per survei: pada bulan Mei, 6 proyek memiliki penulis teknis yang berpartisipasi atau menjawab pertanyaan; 1 proyek tidak memiliki keterlibatan penulis teknis yang berkelanjutan. Pada bulan Agustus, 11 proyek memiliki partisipasi penulis teknis yang sedang berlangsung; tujuh proyek tidak memiliki partisipasi penulis teknis secara berkelanjutan, dan 3 proyek 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 bahwa penulis teknis menjawab pertanyaan.

  1. Jika penulis teknis Anda masih mengerjakan project Anda, apakah ia diberi kompensasi dalam bentuk apa pun?

Grafik batang menunjukkan jumlah proyek yang melaporkan kompensasi proyek 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 penulis teknis mereka tidak dibayar. Pada bulan Agustus, 4 proyek melaporkan membayar penulis teknis mereka dan 7 proyek melaporkan penulis teknis mereka tidak dibayar. Pada bulan November, dua proyek melaporkan pembayaran penulis teknis mereka, dan 5 proyek melaporkan penulis teknis mereka tidak dibayar.

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

Grafik batang yang menampilkan jumlah project yang melaporkan kesuksesan terhadap metrik di setiap survei. Pada bulan Mei, 6 proyek melaporkan metrik mereka telah terpenuhi; 6 proyek mengatakan terlalu cepat untuk dikatakan, dan 2 proyek telah memenuhi metrik yang disesuaikan. Pada bulan Agustus, 16 proyek melaporkan bahwa metrik telah terpenuhi; 3 proyek melaporkan metrik yang disesuaikan telah terpenuhi; dan 2 proyek melaporkan terlalu cepat untuk dikatakan. Pada bulan November, 9 proyek yang melaporkan metrik telah terpenuhi; 3 proyek melaporkan metrik yang disesuaikan telah terpenuhi, dan tidak ada proyek yang melaporkan bahwa metrik tersebut masih terlalu dini untuk dikatakan.

Pertanyaan yang akan datang

Seperti biasa, semakin banyak kita mempelajari dokumentasi dalam open source, semakin banyak hal yang ingin kita pelajari. Di musim mendatang, kami berharap dapat mempelajari:

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

Meskipun ada banyak pertanyaan yang ingin kami selidiki, kami juga ingin menghargai waktu para admin dan pengelola proyek open source yang berpartisipasi dalam Season Dokumen. Prioritas utama program ini adalah mendukung proyek dalam memecahkan masalah mereka dengan dokumentasi.