Laporan Studi Kasus 2021

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

Catatan: Laporan ini merangkum data dari permohonan program asli dan dari studi kasus akhir organisasi. Studi kasus selengkapnya ditautkan dari halaman hasil Dokumen Musim 2021.

Tentang Season Dokumen

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 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 oleh administrator program Season of Docs. Organisasi memberikan mentor untuk bekerja bersama penulis teknis, yang menerima gaji untuk pekerjaan mereka berdasarkan lokasi mereka. Program ini mengukur apakah penulis teknis, mentor, dan admin organisasi puas dengan partisipasi mereka dalam program ini, tetapi tidak mengukur hasil dokumentasi.

Pada tahun 2021, tim Season of Dokumen membuat perubahan signifikan pada program ini, yang mengalihkan fokus ke pengukuran hasil dokumentasi dan memberikan 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 diterapkan 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 mengajukan 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 dibandingkan admin tahun 2020 (93% vs 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 terorganisir, atau usang.
  • Proyek umumnya ingin mengukur efektivitas dokumentasi mereka melalui interaksi, terutama lebih sedikit masalah yang muncul dan lebih banyak pengunjung ke dokumen dan partisipasi dalam proyek.
  • Per November 2022, dengan 25 dari 30 project merespons:
    • 18 proyek mengatakan mereka telah memenuhi metrik awal
    • 5 project 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 para penulis teknis Season of Dokumen mereka (baik sebagai kontributor berkelanjutan atau referensi untuk menjawab pertanyaan)
      • 4 organisasi bekerja sama dengan penulis teknis Season of Dokumen dalam peran berbayar

Sorotan 2021

  • Beberapa project menunjukkan bahwa penulis teknis ingin melanjutkan project mereka setelah berakhirnya program Season of Docs
  • Metanorma meminta banyak penulis teknis berkualifikasi yang mendaftar sehingga mereka menemukan dana yang cocok untuk mempekerjakan penulis tambahan guna bekerja bersama penulis yang didukung Season Dokumen selama program berlangsung
  • Moja Global mendapati bahwa komunitas ini 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 mendaftar dan 30 organisasi open source diterima untuk mengikuti program ini. (Lihat Panduan Membuat Pendaftaran untuk kriteria pemilihan.) Daftar lengkap organisasi yang berpartisipasi dapat ditemukan di situs Season of Docs. 30 organisasi yang diterima 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 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
  • Proyek yang berfokus pada developer, termasuk alat engineering 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 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 memang 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; 3 klausa BSD: lima program; MIT: lima program; GPL 2.0: 4 program; LGPL 2.1: 4 program; Mozilla Public License 2.0: 3 program; Artistic, Boost, dan 2 klausa BSD: masing-masing satu program

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

Masalah utama yang ingin diselesaikan 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 lebih spesifik, lihat halaman hasil Season Dokumen 2021, yang ditautkan 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; Dokumen API, Video, Panduan Memulai, 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 proyek dokumentasi dapat berisi beberapa jenis atau fitur dokumentasi.

Beberapa project secara khusus mereferensikan penggunaan framework Diátaxis sebagai panduan untuk merencanakan jenis dokumentasinya.

Untuk lebih spesifik, lihat halaman hasil Season Dokumen 2021, yang ditautkan ke studi kasus lengkap untuk setiap organisasi.

Anggaran

Pada tahun 2021, permintaan anggaran rata-ratanya 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

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 yang menggunakan dokumentasi/dokumen: 9 proyek; Lebih banyak kontributor/permintaan pull: 8 proyek; Lebih banyak permintaan/kontribusi dokumentasi yang dibuat: 7 proyek; Jumlah total dokumen yang dibuat: 5 proyek; Peningkatan kepuasan dokumentasi (melalui survei), Peningkatan penggunaan proyek, Lebih banyak umpan balik langsung pada halaman dokumentasi: masing-masing satu persen dokumentasi yang dikonversi;

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

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

Untuk lebih spesifik, lihat halaman hasil Season Dokumen 2021, yang ditautkan ke studi kasus lengkap untuk setiap organisasi.

Bekerja sama dengan penulis teknis

Perubahan terbesar pada program Season of Docs pada tahun 2021 melibatkan cara kerja project dengan penulis teknis. Di musim-musim sebelumnya, penulis teknis mendaftar langsung ke Google dan dikoordinasikan oleh administrator program dengan 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 Open Collective 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 menyebut bagian proses ini sebagai bagian yang membutuhkan lebih banyak dukungan. Sebagai tanggapan atas masukan ini, tim Season of Dokumen menambahkan dokumentasi untuk membuat perjanjian penulis teknis ke panduan program.

Rekomendasi perekrutan

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

  • Bagikan materi rekrutmen untuk penulis teknis sedini mungkin, bahkan sebelum Anda diterima dalam program ini. Minta komunitas Anda untuk merujuk kepada kandidat yang potensial.
  • Berbagi secara luas di luar saluran project. Gunakan bahasa inklusif dan secara langsung dorong kandidat dari latar belakang yang kurang terwakili untuk mendaftar.
  • Memahami alat apa yang penting untuk proses pembuatan dokumentasi Anda dan merekrut penulis teknis dengan pengalaman menggunakan alat-alat tersebut.
  • Menyusun ekspektasi yang jelas bagi penulis teknis tentang hasil/capaian 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 Dokumen untuk memberikan bimbingan dan pelatihan.
  • Anggarkan lebih banyak waktu dari yang Anda harapkan untuk orientasi penulis teknis dan menjawab pertanyaan serta memberikan dukungan selama program berlangsung, terutama jika penulis teknis tidak memiliki pengalaman sebelumnya dalam domain proyek Anda.
  • Dokumentasikan proses perekrutan, perekrutan, dan orientasi Anda 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 alumni Google Summer of Code atau Code-In: masing-masing 2

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

Masalah umum dalam bekerja 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 putus sekolah karena COVID atau penyakit lainnya, atau karena tanggung jawab keluarga terkait pandemi. Beberapa proyek melaporkan masalah komunikasi yang melibatkan ketidakcocokan zona waktu atau masalah konektivitas internet.

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

Beberapa proyek mengalami keterlambatan dalam membayar para penulis teknis 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 membuat hal ini lebih jelas dalam dokumentasi untuk program mendatang.

Survei lanjutan

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

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

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

  1. Apakah Anda masih bekerja sama dengan penulis teknis Dokumen di 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; tujuh proyek tidak memiliki partisipasi penulis teknis, 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 adanya penulis teknis yang menjawab pertanyaan.

  1. Jika penulis teknis Anda masih mengerjakan project Anda, apakah ia menerima kompensasi dengan cara apa pun?

Grafik batang yang menampilkan jumlah project yang melaporkan kompensasi project untuk penulis teknis di 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 project melaporkan pembayaran kepada penulis teknis mereka dan 7 project melaporkan bahwa penulis teknis mereka tidak dibayar. Pada bulan November, dua project melaporkan pembayaran kepada penulis teknis mereka, dan 5 project melaporkan bahwa penulis teknis mereka tidak dibayar.

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

Grafik batang yang menampilkan jumlah proyek yang melaporkan kesuksesan terhadap metrik dalam setiap survei. Pada bulan Mei, 6 proyek melaporkan metrik mereka telah terpenuhi; 6 proyek mengatakan terlalu cepat untuk mengatakan, 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 metrik tersebut terlalu cepat untuk dikatakan. Pada bulan November, 9 metrik yang dilaporkan project telah terpenuhi; 3 project melaporkan metrik yang disesuaikan telah terpenuhi, dan tidak ada project yang melaporkan bahwa metrik tersebut masih terlalu cepat untuk diinformasikan.

Pertanyaan mendatang

Seperti biasa, semakin banyak kita belajar tentang dokumentasi di {i>open source<i}, semakin banyak hal yang ingin kita pelajari. Di 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 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 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.