Panduan ini ditujukan untuk membantu organisasi memahami jenis masalah yang dapat diselesaikan dengan dokumentasi yang lebih baik, dan cara memilih metrik yang sesuai untuk project dokumentasi.
Fase saat ini:
Studi kasus dipublikasikan. Lihat
linimasa.
Nyatakan masalah Anda
Sebelum memilih metrik, pastikan Anda memiliki pemahaman yang baik tentang masalah yang ingin Anda pecahkan. Jelaskan sespesifik mungkin.
- "Pull request untuk dokumentasi orientasi kami memerlukan waktu terlalu lama untuk digabungkan. Kontributor menyerah dan pergi."
- "Kami melihat terlalu banyak masalah yang dibuka untuk mendapatkan bantuan dalam memahami kode error."
- "Pipeline CI/CD kami tidak stabil. Terlalu banyak pengujian gagal karena alasan yang tidak dipahami dengan baik."
- "Orang-orang tampak kesal dalam rapat mingguan kami."
Mengembangkan hipotesis
Cari sebab dan akibat. Apa yang mungkin menyebabkan masalah yang Anda nyatakan? Perlu diingat bahwa masalah dapat memiliki beberapa penyebab atau penyebab yang tumpang-tindih.
- "Memerlukan waktu lama untuk menggabungkan permintaan pull untuk dokumentasi orientasi karena kami tidak memiliki panduan yang jelas tentang gaya. Peninjau menunda peninjauan PR karena tidak tahu harus melakukan apa, atau mereka berdiskusi dengan kontributor tentang pemformatan."
- "Pengguna harus membuka masalah karena mereka tidak dapat menemukan informasi tentang kode error dalam dokumentasi."
- "Pengujian CI/CD kami gagal karena kami mengalami batasan paket dan waktu tunggu habis dari penyedia kami".
- "Orang-orang terlihat tidak senang dalam rapat mingguan kami karena rapat diadakan pada pukul 05.30 di zona waktu mereka."
Menyarankan solusi
Apakah masalah ini dapat diselesaikan dengan dokumentasi baru atau yang lebih baik?
- "Jika kita memiliki panduan gaya, committer dapat memeriksanya sebelum mengirimkan PR. Peninjau akan tahu apa yang harus diperiksa. Peninjau dan kontributor tidak perlu berdebat tentang format, nuansa, dan gaya."
- "Jika kami memiliki dokumentasi kode error, pengguna dapat menemukan jawabannya di sana, bukan membuka masalah."
- "Hmm, sepertinya dokumentasi yang lebih baik tidak akan menyelesaikan masalah CI/CD kita."
- "Kita bisa memulai setiap rapat dengan lelucon ketuk-ketuk. Membuat koleksi lelucon ketuk-ketuk akan membantu kita memulai rapat dengan senyuman."
Jadilah spesifik
Dapatkah Anda mengukur masalahnya?
- "Apa yang dimaksud dengan 'memerlukan waktu terlalu lama untuk menggabungkan PR'? Dua bulan? Dua minggu? Berapa lama kontributor akan menunggu peninjauan sebelum menyerah?"
- "Berapa banyak masalah terkait kode error yang termasuk dalam kategori 'terlalu banyak masalah'?"
- "Hmmm … seberapa pemarahkah 'terlalu pemarah'?"
Memeriksa keterukuran
Bagaimana Anda akan memeriksa metrik yang Anda usulkan? Dapatkah hal ini diukur dengan mudah dan akurat? Apakah pengukuran bergantung pada siapa yang melakukan pengukuran?
- "Kami dapat dengan mudah mengukur berapa lama permintaan pull terbuka, dan berapa lama sejak peninjauan diminta. Kami tidak dapat benar-benar mengukur kapan kontributor menyerah."
- "Kita dapat menghitung jumlah masalah yang diberi tag 'kode error' atau menelusuri teks kode error dalam masalah."
- "Kami tidak dapat benar-benar mengukur keluhan orang-orang dengan cara yang sopan atau akurat."
Menambahkan metrik sekunder
Apakah ada metrik lain yang akan membantu Anda memahami apakah dokumentasi Anda menyelesaikan masalah? Apakah metrik target Anda sama dalam setiap kasus?
- "PR yang lebih panjang memerlukan lebih banyak waktu untuk ditinjau; kita harus memiliki nilai minimum yang berbeda untuk ukuran PR yang berbeda. Kita ingin mengukur waktu penggabungan untuk PR berukuran kecil, sedang, besar, dan sangat besar."
- "Kita dapat memeriksa jumlah kunjungan yang diterima dokumentasi kode error dan melihat apakah jumlah tersebut berkorelasi dengan lebih sedikit masalah yang dibuka."
Pilih jangka waktu
- "Kami rasa dua minggu adalah waktu yang wajar untuk menggabungkan PR berukuran kecil hingga sedang; dan semua PR harus digabungkan dalam waktu satu bulan. Jadi, kita akan mengukur setiap dua minggu."
- "Tidak masuk akal untuk memperbarui jumlah masalah terkait kode error setiap hari, karena waktu standar kami untuk menutup masalah adalah satu minggu. Kami akan mengukurnya setiap minggu."
Tentukan target
Berapa banyak perubahan yang perlu Anda lihat dalam metrik yang dipilih untuk menyatakan bahwa project berhasil? Pertimbangkan untuk menetapkan sasaran kuantitatif untuk metrik yang Anda pilih.
- "Jika kita mencapai sasaran untuk menyelesaikan setiap PR baru dalam waktu kurang dari sebulan, itu akan menjadi kesuksesan. Jika waktu rata-rata kami untuk menyelesaikan PR besar berkurang dua minggu, itu akan menjadi kesuksesan besar."
- "Idealnya, kita tidak akan melihat masalah baru terkait error. Namun, kami akan menganggap project kami berhasil jika kami melihat penurunan sebesar 50% dalam jumlah masalah terkait error yang dibuka."
Informasi terkait
- Baca panduan administrator organisasi untuk mendapatkan bantuan terkait tugas terkait laporan.