Fase saat ini:
Hasil diumumkan. Lihat
linimasa.
Gunakan contoh ini untuk membantu Anda membuat laporan studi kasus Anda sendiri.
PicklePlus: Mendokumentasikan Alat Kontribusi GloriousPickle
Organisasi atau Project: Glorious Pickle tautkan ke situs utama organisasi atau project Anda di sini
Deskripsi Organisasi: GloriousPickle (versi saat ini 1.2.3, rilis pertama pada tahun 2009) adalah library berlisensi MIT untuk menghitung rasio garam, gula, cuka, dan rempah-rempah yang sempurna dengan mudah untuk setiap sayuran yang dapat dibuat acar, dalam jumlah mulai dari satu mentimun kecil hingga kargo radish.
Penulis: opsional: cantumkan penulis studi kasus; gunakan nama pengguna jika diminta
Pernyataan Masalah/Abstrak Proposal
Masalah apa yang Anda coba pecahkan dengan dokumentasi baru atau yang ditingkatkan? Link ke halaman proposal di situs project Anda, jika memungkinkan.
Menambahkan bahan ke database bahan alat GloriousPickle memakan waktu dan rumit, serta alat ini tidak memiliki dokumentasi yang baik. Banyak calon kontributor tidak memiliki pengalaman menggunakan git atau membuat permintaan pull. Artinya, GloriousPickle memiliki kesenjangan serius dalam data bahan, dan membuat alat kami kurang berguna. Dengan meningkatkan dokumentasi untuk menambahkan bahan baru, kami berharap dapat mendorong kontributor baru dan lebih banyak pengawetan.
Deskripsi Project
Membuat proposal
Bagaimana Anda mendapatkan proposal Google Season of Dokumen? Proses apa yang digunakan organisasi Anda untuk memutuskan sebuah ide? Bagaimana Anda meminta dan menerapkan masukan?
SIG PickleDocs GloriousPickle mendengar tentang program Google Season of Docs melalui tweet dari Open Source Programs Office Google. SIG mendiskusikan program tersebut dalam rapat dua mingguan mereka, dan setuju untuk membuat proposal. Dua anggota SIG (@KimChiCook dan @Dillicious) secara sukarela mengerjakan draf proposal untuk ditinjau pada pertemuan berikutnya.
Setelah SIG PickleDocs menyetujui draf proposal, email dikirim ke project yang lebih luas untuk meminta masukan. Empat belas anggota komunitas memberikan masukan, termasuk @Glorious ChooselePat, pengelola API penambahan bahan makanan. @GloriousPicklePat menawarkan diri untuk menjadi narasumber selama program berlangsung.
Setelah mendiskusikan dan menyertakan masukan yang diterima, proposal tersebut dikirim ke Panitia Pengarah Project GloriousPickle untuk pemungutan suara. Kelima anggota GPPSC memberikan suara +1 untuk mengirimkan proposal dan permohonan, dan @VinegarViv setuju untuk membantu membuat akun Open Collective yang diperlukan untuk berpartisipasi dalam program dan mengawasi pembayaran.
Anggaran
Sertakan bagian singkat tentang anggaran Anda. Bagaimana cara Anda memperkirakan pekerjaan tersebut? Apakah ada pengeluaran tak terduga? Apakah Anda akhirnya membelanjakan lebih sedikit dari jumlah hibah yang diberikan? Apakah Anda mengalokasikan dana dengan benar atau apakah ada item yang Anda alokasikan lebih/kurang/tidak perlu? Apakah Anda memiliki dana lain di luar Google Season of Docs yang dapat Anda gunakan?
Dua anggota Glorious Pickle PickleDocs SIG bekerja sebagai penulis teknis (satu di Eropa, dan satu di Argentina). Mereka membantu kami memperkirakan pekerjaan dan menemukan anggaran project serupa, dengan membandingkan pekerjaan draf proposal yang telah mereka lakukan sebelumnya. Kami juga memiliki sisa dana sponsor sebesar US$1.000 yang tidak dibatasi dari konvensi PicklePals 2019 yang kami alokasikan untuk project ini.
Biaya yang tidak terduga adalah membantu penulis teknis kami menyewa hotspot Wi-Fi, karena ia berada di area yang terkena dampak kebakaran hutan dan kehilangan akses internet di rumahnya. Kami juga akhirnya mengirimkan lebih sedikit t-shirt untuk peserta dari yang kami rencanakan, jadi seimbang.
Selain itu, kami memutuskan untuk memberikan kompensasi kepada kontributor Glorious Pickle, @Piccalily (yang pernah menjadi copyeditor profesional dalam kehidupannya yang biasa-biasa saja) untuk membantu melakukan {i>copyediting<i} dan pemeriksaan tata bahasa dokumentasi yang dibuat oleh penulis teknis.
Peserta
Siapa yang mengerjakan project ini (gunakan nama pengguna jika diminta oleh peserta)? Bagaimana Anda menemukan dan mempekerjakan penulis teknis Anda? Bagaimana Anda menemukan sukarelawan atau peserta berbayar lainnya? Apa peran mereka? Apakah ada yang tidak ikut? Apa yang Anda pelajari tentang perekrutan, komunikasi, dan manajemen project?
Tim inti yang mengerjakan project ini adalah:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (bantuan admin, GPPSC)
- @BBChips, @GloriousPicklePat (para pakar di bidang ilmu tertentu)
- Sam Scribe (penulis teknis)
Kami menemukan Sam Scribe melalui daftar repositori GitHub Google Season Dokumen. Kami pikir pengalamannya (Sam pernah bekerja untuk majalah kuliner serta menulis dokumentasi untuk situs) cocok dengan project kami. Sam bergabung dalam panggilan SIG PickleDocs dua mingguan dan membahas project ini dengan kami, serta memberikan beberapa saran yang sangat berharga yang kami sertakan dalam proposal. Kami juga telah menghubungi dua penulis teknis lainnya yang kami kenal melalui jaringan anggota SIG, tetapi keduanya tidak tersedia selama rentang waktu program ini.
Karena zona waktu Sam hanya tumpang-tindih beberapa jam dengan sebagian besar anggota SIG PickleDocs, kami mengirimkan panggilan di forum diskusi kami untuk Pickler yang berada di zona waktu Sam dan memahami proses penambahan bahan. @BBChips menawarkan diri untuk menjawab pertanyaan Sam dan membantunya menemukan pakar lain sesuai kebutuhan. @GloriousPicklePat juga menawarkan diri untuk membantu Sam memahami arsitektur dasar alat dan kemungkinan pesan error dari API, serta memberikan bantuan GitHub dan git.
Sayangnya, di tengah-tengah program @VinegarViv, ia harus mundur dari proyek karena alasan pribadi. Anggota GPPSC, @GherKen, memutuskan untuk menjawab pertanyaan administratif dan pembayaran.
Setelah beberapa pertanyaan terlewat (GloriousPickle menggunakan instance Slack gratis dan terkadang diskusi berjalan begitu cepat sehingga kami kehilangan percakapan karena batas arsip bergulir), kami belajar bahwa kita harus menyimpan daftar pertanyaan yang sedang berjalan dalam dokumen bersama (kami menggunakan Google Dokumen bersama). Anggota SIG PickleDocs memeriksanya sebelum setiap rapat dan memastikan untuk mendapatkan jawaban sebelum rapat berakhir. Sam dapat langsung menghubungi @BBChips untuk mengajukan pertanyaan mendesak.
Kami sangat senang bekerja sama dengan Sam dan Sam, selain memperbarui dokumentasi GloriousPickle, telah menjadi penggemar pickle yang rajin.
Linimasa
Berikan ringkasan singkat tentang linimasa project Anda (tunjukkan perkiraan tanggal akhir atau pencapaian perantara jika project sedang berlangsung).
Selagi menunggu program Google Season of Docs mengumumkan organisasi yang berpartisipasi, anggota PickleDocs SIG melakukan penelusuran untuk menemukan karya sebelumnya yang menurut kami akan berguna bagi Sam. Selama sebulan, kami menemukan beberapa catatan dari upaya sebelumnya untuk memperbarui dokumentasi yang terhenti, dan kami juga mengerjakan bagian-bagian dari materi audit kematangan dokumentasi di repo opendocs Google.
Setelah kami mendapatkan kabar baik bahwa kami terpilih untuk Google Season of Docs, Sam dan SIG PickleDocs bertemu dan menyusun jadwal kasar:
| Tahap | Diselesaikan Oleh |
|---|---|
| Meninjau audit dokumen | 7 Mei |
| Kasus penggunaan log gesekan 3 | 14 Mei |
| Meninjau log gesekan dengan @GloriousPicklePat dan @BBChips, menjawab kueri | 28 Mei |
| Draf pertama kasus penggunaan dokumen yang diperbarui 1 | 25 Juni |
| Draf kasus penggunaan 1 ditinjau oleh @GloriousPicklePat & @KimChiCook | 2 Juli |
| Draf pertama kasus penggunaan dokumen yang diperbarui 2 | 2 Juli |
| Draf kasus penggunaan 2 ditinjau oleh @GloriousPicklePat & @Dillicious | 9 Juli |
| Draf pertama kasus penggunaan dokumen yang diperbarui 3 | 9 Juli |
| Draf kasus penggunaan 3 ditinjau oleh @Dillicious & @KimChiCook | 16 Juli |
| Semua kueri yang dijawab pada semua kasus penggunaan | 30 Juli |
| Sebagian besar SIG PickleDocs sedang berlibur pada 1-20 Agustus | -- |
| Mulai pengujian dokumen baru di komunitas (dokumen dipublikasikan sebagai draf di situs Glorious Choosele) | 21 Agustus |
| Masukan pengujian digabungkan | 10 September |
| Peninjauan dan pemeriksaan ulang dokumen baru | 17 September |
| Status draf dokumen dihapus, dokumen diluncurkan secara resmi | 28 September |
| Proses untuk memperbarui dokumentasi yang dibuat | 1 November |
| Studi kasus ini dibuat | 8 November |
| Studi kasus dikirim | 16 November |
Dalam anggaran proposal, kami memperkirakan bahwa penulis teknis akan menghabiskan waktu 10-15 jam per minggu untuk mengerjakan project kami. Sam mencatat waktu yang dihabiskan dan rata-rata 11,5 jam per minggu.
Hasil
Apa yang dibuat, diperbarui, atau diubah? Sertakan link ke dokumentasi yang dipublikasikan jika tersedia. Apakah ada hasil dalam proposal yang tidak dibuat? Cantumkan juga hal tersebut.
Tiga kasus penggunaan utama didokumentasikan dengan panduan cara penggunaan lengkap untuk pengguna:
Cara menambahkan bahan baru ke GloriousPickle
Cara menambahkan bahan varian ke GloriousPickle
Cara memperbarui atau memperbaiki bahan di Glorious Pickle
Panduan ini juga menyertakan template permintaan pull baru untuk mempermudah kontribusi.
Selain itu, selama proyek berlangsung, Sam membuat Pickle Glossary kecil untuk istilah yang mereka pelajari, yang juga diterbitkan di situs proyek Glorious Choosele.
Kami menambahkan petunjuk untuk memperbarui panduan cara kerja pengguna ini ke wiki project kami.
Kami telah menyertakan pembuatan tips cepat untuk kontributor yang baru menggunakan GitHub untuk membantu mereka menggunakan proses dan alat kami, tetapi setelah melihat referensi yang tersedia, kami dapat melakukan fork pada tips cepat project lain.
Metrik
Metrik apa yang Anda pilih untuk mengukur keberhasilan project? Apakah Anda dapat mengumpulkan metrik tersebut? Apakah metrik berkorelasi dengan baik atau buruk dengan hasil yang Anda inginkan untuk project tersebut? Apakah metrik Anda berubah sejak proposal Anda?
Dalam proposal kami, kami mengusulkan dua metrik:
- jumlah permintaan pull terkait bahan
- jumlah permintaan pull dari kontributor baru
Untuk bulan September (bulan penuh pertama sejak publikasi draf dokumentasi), kami melihat peningkatan permintaan pull terkait bahan sebesar 5% (dari 20 pada Agustus menjadi 21 pada September) dan kami melihat tiga kontributor baru yang membuat total empat permintaan pull (dibandingkan dengan dua kontributor baru yang membuat dua permintaan pull pada Agustus). Kami berencana melacak metrik ini setiap bulan.
Mulai 1 Januari, kami juga akan melacak jumlah kontributor yang telah membuat lebih dari tiga kontribusi secara keseluruhan, mulai setiap tiga bulan setelah dokumentasi dipublikasikan.
Secara anekdotal, kami yakin dokumentasi baru ini telah membuat perbedaan dalam memungkinkan kontributor baru menambahkan ke database bahan GloriousPickle—satu kontributor baru menyebutkan dalam komentar PR-nya bahwa ia telah mencoba sebelumnya, tetapi belum menyelesaikan pembaruannya karena tidak memahami prosesnya.
Analisis
Apa yang berjalan dengan baik? Apa yang tidak terduga? Hambatan atau kemunduran apa yang Anda hadapi? Apakah Anda menganggap project Anda berhasil? Mengapa atau mengapa tidak? (Jika Anda terlalu dini untuk menyampaikannya, jelaskan kapan Anda berharap dapat menilai keberhasilan proyek Anda.)
Kami sangat senang dengan hasil project Google Season of Docs dan menganggapnya sebagai sebuah kesuksesan. Dokumentasi baru ini jelas dan bermanfaat, dan kami telah melihat beberapa peningkatan jumlah permintaan pull terkait bahan dan jumlah permintaan pull dari kontributor baru.
Kami juga senang karena hampir seluruh komunitas Glorious Pickle berpartisipasi, dengan memberikan masukan terkait proposal asli dan menguji dokumen baru dalam bentuk draf.
Kami memang menghadapi beberapa kendala yang tidak terduga—kami bersyukur bahwa kebakaran hutan di negara bagian Sam tidak menyebabkan kerusakan lebih lanjut selain pemadaman internet. Selain itu, kami mohon maaf karena @VinegarViv tidak dapat bergabung dalam project ini. Kami mendoakan yang terbaik untuknya dan keluarganya, dan berharap dapat segera bertemu dengannya lagi.
Satu hal yang tidak kami sadari hingga Sam mulai mengerjakan dokumentasi adalah banyaknya istilah dan akronim terkait pickle yang tidak akan dikenali oleh seseorang yang bergabung ke project kami tanpa latar belakang pickling. Namun, Sam membuat daftar setiap istilah yang tidak dikenal dan mendefinisikannya melalui risetnya sendiri serta dengan meminta penjelasan dan referensi dari anggota komunitas. Glosarium Acar ini akan sangat membantu dalam menyambut lebih banyak orang ke dalam komunitas pengacaran di masa mendatang.
Ringkasan
Dalam 2-4 paragraf, rangkum pengalaman project Anda. Soroti apa yang telah Anda pelajari, dan apa yang akan Anda pilih untuk dilakukan secara berbeda di masa mendatang. Saran apa yang akan Anda berikan kepada project lain yang mencoba memecahkan masalah serupa dengan dokumentasi?
Singkatnya, pengalaman kami sangat luar biasa. Kami telah mencapai hasil dokumentasi dan metrik kami tampaknya sesuai dengan sasaran kami.
Sebagian besar kesuksesan project ini adalah karena kami beruntung dapat bekerja sama dengan penulis teknis kami, Sam Scribe. [Saya tidak menulis ini—Sam] Meskipun Sam tidak memiliki latar belakang dalam pickling atau pengalaman dengan GitHub, sebagai penulis teknis berpengalaman, ia merasa nyaman untuk mempelajari area subjek baru, mengajukan pertanyaan, dan melakukan riset. Sam dengan cepat memahami tidak hanya alat project kami (kami menggunakan papan kanban untuk melacak pekerjaan), tetapi juga lelucon acar kami. Kami sangat senang karena Sam telah menemukan bug pengawetan dan kami telah 'menampung'nya di komunitas kami.
Kami akan menyarankan proyek lain untuk:
- Buat proposal yang kecil dan mudah dikelola. (Awalnya kami ingin menyertakan dokumentasi untuk menggunakan estimator kami dengan mesin pengawetan batch industri dalam proposal kami, dan hanya meninggalkannya karena salah satu anggota komunitas kami yang sangat terlibat dalam mesin pengawetan open source akan menulis tesis PhD-nya selama program berlangsung.) Kami akhirnya memiliki lebih dari cukup pekerjaan untuk membuat Sam sibuk.
- Manfaatkan jaringan Anda saat mencari penulis teknis. Minta rekomendasi dari semua orang di komunitas Anda. Meskipun kami menemukan Sam melalui GitHub Google Season of Docs, kami merasa yakin untuk bekerja sama dengannya karena kami telah berbicara dengan beberapa orang selama periode pendaftaran.
- Sambut penulis teknis Anda ke komunitas Anda. Sam memberi tahu kami bahwa sikap antusias para Glorious Chooselers memudahkan saya untuk mengajukan pertanyaan.
- Bantu penulis teknis Anda mendapatkan keterampilan open source. Sam belum pernah menggunakan git sebelumnya, tetapi setelah mengikuti beberapa tutorial, ia bisa memahaminya dengan cepat. Awalnya, Sam khawatir dengan banyaknya masukan yang mungkin ia dapatkan dari komunitas dan cara memasukkannya, tetapi model 'konsensus kasar' komunitas kami ('konsensus tercapai jika semua masalah ditangani, tetapi tidak selalu diakomodasi') membuat Sam yakin untuk mengatasi kritik menggunakan keahlian penulisan teknisnya.
Lampiran
Jika Anda memiliki materi lain yang ingin ditautkan (misalnya, jika Anda ingin membagikan kontrak untuk bekerja sama dengan penulis teknis, atau template untuk project dokumentasi, atau referensi dokumentasi terbuka lainnya, Anda dapat mencantumkan dan menautkannya di sini). Lampiran juga merupakan tempat yang tepat untuk mencantumkan link ke alat atau referensi dokumentasi yang Anda gunakan, atau tempat untuk menambahkan ucapan terima kasih atau penghargaan yang mungkin tidak sesuai dengan bagian di atas.
Ucapan terima kasih
Tim kami ingin mengucapkan terima kasih kepada orang dan hal berikut:
- @Dillicious ingin berterima kasih kepada partnernya dan juga radio hip hop low-fi
- @KimChiCook ingin berterima kasih kepada 할머니-nya karena telah mengajarinya cara membuat acar
- @Piccalily ingin berterima kasih kepada Chicago Manual of Style Online
- @GherKen ingin berterima kasih kepada ketiga anaknya karena telah menghabiskan semua acar yang ia buat
- @VinegarViv ingin berterima kasih kepada anggota tim lainnya karena telah membantunya mengundurkan diri
- @BBChips ingin berterima kasih kepada makanan non-acar terbaik yang tersedia, Wafer Karamel Tunnock
- @GloriousPicklePat ingin berterima kasih kepada PickleDocs SIG karena telah mengerjakan project ini
- Sam Scribe ingin berterima kasih kepada seluruh komunitas GloriousPickle, terutama Picklers yang mengiriminya toples pengawetan selama kelangkaan toples pada musim panas 2021, yang memulai perjalanannya untuk membuat banyak acar lezat.