Memilih metrik yang tepat untuk proyek Anda

Panduan ini ditujukan untuk membantu organisasi memahami jenis masalah yang dapat dipecahkan dengan dokumentasi yang lebih baik, dan cara memilih metrik yang sesuai untuk project dokumentasi.

Fase saat ini:
Program Season of Docs 2021 berakhir pada 14 Desember 2021. Lihat linimasa.

Nyatakan masalah Anda

Sebelum memilih metrik, pastikan Anda memiliki pemahaman yang baik tentang masalah yang ingin dipecahkan. 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 meninjau PR karena tidak tahu apa yang harus dilakukan, 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 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.”

Berikan detail spesifik

Dapatkah Anda mengukur masalahnya?

  • “Apa yang dimaksud dengan 'perlu 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 dianggap '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 Anda? 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.”
  • “Kami dapat memeriksa jumlah kunjungan yang diterima dokumentasi kode error kami 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 sekali.”
  • “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 tersebut berhasil? Pertimbangkan untuk menetapkan sasaran kuantitatif untuk metrik yang Anda pilih.

  • "Jika kami 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 berhasil jika kami melihat penurunan sebesar 50% pada masalah terkait error yang dibuka.”