Fase saat ini:
Pengembangan dokumentasi. Lihat
linimasa.
Gunakan contoh ini untuk membantu Anda membuat laporan studi kasus Anda sendiri.
PicklePlus: Mendokumentasikan Alat Kontribusi GloriousChoosele
Organisasi atau Project: Glorious Pickle link ke situs utama organisasi atau project Anda di sini
Deskripsi Organisasi: Gloriousdip (versi 1.2.3, rilis pertama tahun 2009) adalah perpustakaan berlisensi MIT untuk dengan mudah menghitung rasio sempurna garam, gula, cuka, dan rempah-rempah untuk setiap acar sayuran yang mungkin, dalam jumlah mulai dari satu mentimun bayi soliter untuk kontainer-kapal lobak.
Penulis: opsional: cantumkan penulis studi kasus; gunakan nama pengguna jika diminta
Pernyataan Masalah/Proposal Abstrak
Masalah apa yang Anda coba selesaikan dengan dokumentasi baru atau yang ditingkatkan? Berikan link ke halaman proposal di situs project Anda, jika memungkinkan.
Menambahkan bahan-bahan ke database bahan alat Gloriousdip memerlukan waktu dan rumit, serta alat ini tidak memiliki dokumentasi yang baik. Banyak calon kontributor yang tidak memiliki pengalaman menggunakan git atau membuat permintaan pull. Ini berarti Gloriouspickuple memiliki celah serius dalam data bahan kami, dan membuat alat kami kurang berguna. Dengan menyempurnakan dokumentasi untuk penambahan bahan-bahan baru, kami berharap dapat mendorong kontributor baru dan lebih banyak pengawetan!
Deskripsi Project
Membuat proposal
Bagaimana Anda mendapatkan proposal untuk Google Season of Docs? Proses apa yang digunakan organisasi Anda untuk memutuskan suatu ide? Bagaimana cara Anda mengumpulkan dan menerapkan masukan?
GloriousChoosele PickleDocs SIG mendengar tentang program Google Season of Docs melalui tweet dari Kantor Program Open Source Google. SIG mendiskusikan program tersebut pada pertemuan dua mingguan mereka, dan setuju untuk membuat proposal. Dua anggota SIG (@KimChiCook dan @Dillicious) mengajukan diri untuk mengerjakan draf proposal untuk ditinjau pada pertemuan berikutnya.
Setelah PickleDocs SIG menyetujui draf proposal, email dikirim ke project yang lebih luas untuk meminta masukan. Empat belas anggota komunitas menyarankan untuk memberikan masukan, termasuk @GloriousChooselePat, pengelola API penambahan bahan. @GloriousChooselePat secara sukarela menjadi referensi selama program ini berlangsung.
Setelah mendiskusikan dan menggabungkan masukan yang diterima, proposal dikirimkan ke Komite Pengarah Proyek Gloriousdiple untuk pemungutan suara. Kelima anggota GPPSC memilih +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 pendek pada anggaran Anda. Bagaimana Anda memperkirakan pekerjaannya? Apakah ada pengeluaran yang tidak terduga? Apakah Anda membelanjakan lebih sedikit daripada penghargaan hibah? Apakah Anda mengalokasikan dana dengan benar atau beberapa item yang Anda anggarkan lebih banyak/lebih sedikit/tidak diperlukan? Apakah Anda memiliki dana lain di luar Google Season Dokumen yang dapat Anda gunakan?
Dua anggota Gloriouslet PickleDocs SIG pernah bekerja sebagai penulis teknis (satu di Eropa dan satu lagi di Argentina). Mereka membantu kami memperkirakan pekerjaan dan menemukan anggaran proyek yang serupa, membandingkan pekerjaan draf proposal yang mereka lakukan sebelumnya. Kami juga memiliki sisa US$1000 dalam bentuk uang sponsor tak terbatas dari konvensi PicklePals 2019 yang kami alokasikan untuk proyek tersebut.
Biaya tak terduga membantu penulis teknis kami menyewa hotspot Wi-Fi, karena ia berada di area yang terkena dampak kebakaran hutan dan kehilangan akses internet di rumah mereka. Kami juga akhirnya mengirimkan lebih sedikit kaos kepada peserta dari yang kami rencanakan, sehingga seimbang.
Selain itu, kami memutuskan untuk memberikan kompensasi kepada kontributor GloriousChoosele, @Piccalily (yang pernah menjadi copyeditor profesional dalam kehidupannya yang tidak memusingkan) untuk membantu melakukan copyediting dan memeriksa tata bahasa dokumentasi yang dibuat oleh penulis teknis.
Peserta
Siapa yang mengerjakan proyek ini (gunakan nama pengguna jika diminta oleh peserta)? Bagaimana Anda menemukan dan mempekerjakan penulis teknis? Bagaimana Anda menemukan sukarelawan atau peserta berbayar lain? Peran apa saja yang mereka miliki? Apakah ada yang berhenti? Apa yang Anda pelajari tentang rekrutmen, komunikasi, dan manajemen project?
Tim inti yang mengerjakan proyek ini adalah:
- @Dillicious, @KimChiCook (ChooseleDocs SIG)
- @Piccalily (editor salinan)
- @GherKen, @VinegarViv (bantuan admin, GPPSC)
- @BBChips, @GloriousChooselePat (ahli materi pokok)
- Sam Scribe (penulis teknis)
Kami menemukan Sam Scribe melalui daftar repositori GitHub Google Season of Docs. Kami rasa pengalaman mereka (Sam pernah bekerja untuk majalah kuliner serta menulis dokumentasi untuk situs web) sangat cocok dengan proyek kami. Sam bergabung dengan panggilan dua mingguan PickleDocs SIG dan mendiskusikan proyek dengan kami. Ia juga memberikan beberapa saran berharga yang kami masukkan ke dalam proposal. Kami juga menghubungi dua penulis teknis lain yang kami kenal melalui jaringan anggota SIG, tetapi keduanya tidak pernah tersedia selama jangka waktu program ini.
Karena zona waktu Sam hanya tumpang-tindih beberapa jam dengan sebagian besar anggota PickleDocs SIG, kami mengirim panggilan di forum diskusi kami untuk Picklers yang berada di zona waktu Sam dan familier dengan proses penambahan bahan. @BBChips mengajukan diri untuk menjawab pertanyaan Sam dan membantunya menemukan pakar lain sesuai kebutuhan. @GloriousChooselePat juga menjadi sukarelawan untuk membantu Sam memahami arsitektur dasar alat tersebut dan kemungkinan pesan error dari API, serta menyediakan bantuan GitHub dan git.
Sayangnya, di tengah-tengah program, @VinegarViv harus mundur dari proyek karena alasan pribadi. Anggota GPPSC @GherKen bertindak untuk menangani pertanyaan administratif dan pembayaran.
Setelah beberapa pertanyaan yang terlewatkan (Gloriousdip menggunakan instance Slack gratis dan kadang-kadang diskusi bergerak begitu cepat sehingga kami kehilangan percakapan karena batas bergulirnya arsip) kami belajar bahwa kami harus menyimpan daftar pertanyaan yang berjalan dalam dokumen bersama (kami menggunakan Dokumen Google bersama). Anggota PickleDocs SIG memeriksanya sebelum setiap rapat dan memastikan untuk mendapatkan jawaban sebelum rapat berakhir. Sam dapat langsung mengirim ping ke @BBChips untuk mengajukan pertanyaan mendesak.
Kami sangat senang dapat bekerja sama dengan Sam dan Sam. Selain memperbarui dokumentasi GloriousChoosele, kami menjadi bersemangat untuk memilih.
Linimasa
Berikan ringkasan singkat tentang linimasa project Anda (tunjukkan perkiraan tanggal akhir atau pencapaian menengah jika project sedang berlangsung).
Sementara kami menunggu program Google Season of Docs mengumumkan organisasi yang berpartisipasi, anggota PickleDocs SIG menelusuri pekerjaan sebelumnya yang menurut kami akan berguna bagi Sam. Selama sebulan, kami menemukan beberapa catatan dari upaya awal untuk memperbarui dokumentasi yang terhenti, dan kami juga mengerjakan beberapa bagian materi audit kematangan dokumentasi dalam repo opendocs Google.
Setelah mendapat kabar baik bahwa kami terpilih untuk Google Season Dokumen, Sam dan PickleDocs SIG bertemu dan menyusun jadwal yang kasar:
| Tahap | Diselesaikan Oleh |
|---|---|
| Tinjau audit dokumen | 7 Mei |
| Kasus penggunaan log gesekan 3 | 14 Mei |
| Tinjau log friksi dengan @GloriousChooselePat dan @BBChips untuk menjawab pertanyaan | 28 Mei |
| Draf pertama kasus penggunaan dokumen yang diperbarui 1 | 25 Juni |
| Draf kasus penggunaan 1 ditinjau oleh @GloriousChooselePat & @KimChiCook | 2 Juli |
| Draf pertama kasus penggunaan dokumen yang diperbarui 2 | 2 Juli |
| Draf kasus penggunaan 2 ditinjau oleh @GloriousChooselePat & @Dillicious | 9 Juli |
| Draf pertama kasus penggunaan dokumen yang diperbarui 3 | 9 Juli |
| Draf kasus penggunaan 3 ditinjau oleh @Dillicious & @KimChiCook | 16 Juli |
| Semua pertanyaan yang dijawab pada semua kasus penggunaan | 30 Juli |
| Sebagian besar PickleDocs SIG sedang berlibur pada 1-20 Agustus | -- |
| Memulai pengujian dokumen baru di komunitas (dokumen yang dipublikasikan sebagai draf di situs GloriousChoosele) | 21 Agustus |
| Masukan pengujian disertakan | 10 September |
| Salin edit dan baca ulang dokumen baru | 17 September |
| Status draf dokumen dihapus, dokumen resmi diluncurkan | 28 September |
| Proses untuk memperbarui dokumentasi yang dibuat | 1 November |
| Studi kasus ini membuat | 8 November |
| Studi kasus dikirim | 16 November |
Dalam anggaran proposal kami, kami memperkirakan bahwa penulis teknis akan menghabiskan 10-15 jam per minggu untuk mengerjakan proyek kami. Sam menyimpan catatan 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 kerja dalam proposal yang tidak dibuat? Cantumkan juga hal tersebut.
Tiga kasus penggunaan utama didokumentasikan dengan panduan cara kerja pengguna lengkap:
Cara menambahkan bahan baru ke GloriousChoosele
Cara menambahkan bahan varian ke Gloriouspickuple
Cara memperbarui atau memperbaiki bahan di Gloriouspickuple
Panduan ini juga menyertakan template permintaan pull baru untuk mempermudah kontribusi.
Selain itu, selama proyek, Sam membuat daftar istilah yang mereka pelajari, yang juga dipublikasikan di situs proyek Gloriousdip.
Kami menambahkan petunjuk untuk memperbarui panduan cara kerja pengguna ini ke wiki proyek kami.
Kami telah menyertakan lembar contekan bagi kontributor yang baru mengenal GitHub untuk membantu mereka menggunakan proses dan alat kami. Namun, begitu kami melihat resource yang tersedia, kami dapat mengambil lembar contekan project lain sebagai gantinya.
Regresi
Metrik apa yang Anda pilih untuk mengukur keberhasilan project tersebut? Apakah Anda dapat mengumpulkan metrik tersebut? Apakah metrik berkorelasi dengan baik atau buruk dengan hasil yang Anda inginkan untuk proyek ini? 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 penerbitan draf dokumentasi) kami melihat kenaikan 5% dalam permintaan pull terkait bahan (dari 20 pada Agustus hingga 21 pada September) dan kami melihat tiga kontributor baru yang membuat total empat permintaan pull (vs dua kontributor baru yang membuat dua permintaan pull pada bulan Agustus). Kami berencana untuk melacak metrik ini setiap bulan.
Mulai 1 Januari, kami juga akan melacak jumlah kontributor yang telah memberikan lebih dari tiga kontribusi secara keseluruhan, mulai tiga bulanan setelah dokumentasi dipublikasikan.
Secara diam-diam, kami percaya dokumentasi baru ini telah membuat perbedaan dalam memungkinkan kontributor baru untuk menambahkan ke database bahan Gloriouslet — satu kontributor baru menyebutkan dalam komentar PR mereka bahwa mereka telah mencoba sebelumnya, tetapi belum menyelesaikan update karena mereka tidak memahami prosesnya.
Analisis
Hal apa yang berjalan dengan baik? Apa yang tidak diharapkan? Rintangan atau kemunduran apa yang Anda hadapi? Apakah Anda menganggap proyek Anda berhasil? Mengapa atau mengapa tidak? (Jika terlalu dini untuk mengatakannya, jelaskan kapan Anda dapat menilai keberhasilan proyek Anda.)
Kami sangat senang dengan hasil proyek Google Season Dokumen ini dan menganggapnya sukses. Dokumentasi baru ini jelas dan bermanfaat, dan kami telah melihat pertumbuhan jumlah permintaan pull terkait bahan dan jumlah permintaan pull dari kontributor baru.
Kami juga senang karena hampir seluruh komunitas GloriousChoosele berpartisipasi, dengan memberikan masukan terkait proposal asli dan dengan menguji dokumen baru dalam bentuk draf.
Kami memang menghadapi beberapa rintangan tak terduga—kami bersyukur bahwa kebakaran hutan di negara bagian Sam tidak menyebabkan kerusakan yang lebih parah daripada gangguan internet. Selain itu, kami menyayangkan kehilangan @VinegarViv dari proyek ini. Kami mendoakan yang terbaik baginya dan keluarganya dan berharap bisa segera bertemu lagi dengannya.
Satu hal yang tidak kami sadari sampai Sam mulai mengerjakan dokumentasinya adalah berapa banyak istilah dan akronim terkait acar yang akan asing bagi seseorang yang masuk ke proyek kami tanpa latar belakang acar. Namun, Sam membuat daftar istilah yang tidak dikenalnya dan mendefinisikannya melalui penelitiannya sendiri, serta dengan meminta penjelasan dan referensi dari anggota komunitas. Daftar Istilah Acar ini akan sangat membantu dalam menyambut lebih banyak orang ke dalam komunitas acar di masa mendatang.
Ringkasan
Rangkum pengalaman project Anda dalam 2-4 paragraf. 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 terkait dokumentasi?
Singkatnya, pengalaman kami sangat menyenangkan! Kami telah mencapai hasil dokumentasi dan metrik kami tampaknya sejalan dengan tujuan kami.
Sebagian besar keberhasilan proyek ini adalah betapa beruntungnya kami bekerja sama dengan penulis teknis kami, Sam Scribe. [Saya tidak menulis ini—Sam] Meskipun Sam tidak memiliki latar belakang mengasin atau berpengalaman dengan GitHub, sebagai penulis teknis berpengalaman, ia merasa nyaman terjun ke bidang subjek baru, mengajukan pertanyaan, dan melakukan penelitian. Sam dengan cepat memanfaatkan alat-alat proyek kami (kami menggunakan papan kanban untuk memantau pekerjaan), tetapi juga lelucon acar kami. Kami sangat senang bahwa Sam telah menangkap kumbang acar dan kami telah 'membungkusnya' di komunitas kita.
Kami akan menyarankan project lain untuk:
- Jaga agar proposal Anda tetap kecil dan mudah dikelola. (Kami awalnya ingin menyertakan dokumentasi untuk menggunakan penaksir kami dengan mesin pengawet batch industri dalam proposal kami, dan hanya meninggalkannya karena salah satu anggota komunitas kami yang sangat terlibat dalam mesin acar open source akan menulis skripsinya selama program ini.) Akhirnya, kami mendapat lebih dari cukup pekerjaan untuk membuat Sam sibuk!
- Manfaatkan jaringan Anda saat mencari penulis teknis. Minta semua orang di komunitas Anda untuk memberikan rekomendasi. Meskipun kami menemukan Sam melalui Google Season of Docs GitHub, kami merasa percaya diri bekerja dengannya karena kami telah berbicara dengan beberapa orang selama periode pendaftaran.
- Sambut penulis teknis di komunitas Anda! Sam memberi tahu kami bahwa sikap antusias GloriousChooselers memudahkan untuk mengajukan pertanyaan.
- Bantu penulis teknis Anda mendapatkan keterampilan open source. Sam belum pernah menggunakan {i>git<i} sebelumnya, tetapi setelah melalui beberapa tutorial, mereka menjadi cepat menguasainya. Pada awalnya, Sam khawatir dengan jumlah masukan yang mungkin didapatkan dari komunitas dan cara menerapkannya, tetapi model 'konsensus kasar' komunitas kami ('konsensus tercapai saat semua masalah ditangani, tetapi belum tentu diakomodasi') membuat Sam percaya diri dalam menanggapi kritik menggunakan keahlian penulisan teknisnya.
Lampiran
Jika Anda memiliki materi lain yang ingin ditautkan (misalnya, jika Anda membuat kontrak untuk bekerja dengan penulis teknis yang ingin Anda bagikan, 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 ucapan terima kasih yang mungkin tidak sesuai dengan bagian di atas.
Ucapan terima kasih
Tim kami ingin mengakui orang-orang dan hal-hal berikut:
- @Dillicious ingin berterima kasih kepada pasangannya dan juga radio hip hop low-fi
- @KimChiCook ingin berterima kasih kepada 할머니 yang telah mengajarinya cara membuat acar
- @Piccalily ingin berterima kasih kepada Panduan Gaya Online Chicago
- @GherKen ingin berterima kasih kepada ketiga anaknya karena telah memakan semua acar yang bisa dia buat
- @VinegarViv ingin berterima kasih kepada anggota tim lainnya karena telah membantunya mengundurkan diri
- @BBChips ingin mengucapkan terima kasih kepada non-acar makanan terbaik yang tersedia, Wafer Karamel Tunnock's
- @GloriousChooselePat ingin berterima kasih kepada PickleDocs SIG karena telah menangani project ini
- Sam Scribe ingin mengucapkan terima kasih kepada seluruh komunitas GloriousChoosele, tetapi terutama para Pickler yang mengirimi mereka stoples pengalengan selama kekurangan stoples pada musim panas 2021, memulai mereka di jalan menuju banyak acar lezat!