Memilih metrik yang tepat untuk proyek Anda

Panduan ini dimaksudkan untuk membantu organisasi memahami jenis masalah apa yang dapat diselesaikan dengan dokumentasi yang lebih baik, dan cara memilih metrik yang tepat untuk project dokumentasi.

Fase saat ini:
Pengembangan dokumentasi. Lihat linimasa.

Nyatakan masalah Anda

Sebelum memilih metrik, pastikan Anda memiliki pemahaman yang baik tentang masalah yang coba dipecahkan. Jelaskan sespesifik mungkin.

  • "Permintaan penarikan untuk dokumentasi orientasi kami memerlukan waktu terlalu lama untuk digabungkan. Kontributor menyerah dan menyerah."
  • "Kami melihat terlalu banyak masalah yang terbuka sehingga kami dapat memahami kode error."
  • "Pipeline CI/CD kami tidak stabil. Terlalu banyak pengujian yang gagal karena alasan yang kurang dipahami."
  • "Orang-orang tampak kesal dalam pertemuan mingguan kami."

Mengembangkan hipotesis

Mencari sebab dan akibat. Apa kemungkinan penyebab masalah yang telah Anda nyatakan? Ingatlah bahwa masalah dapat memiliki beberapa penyebab atau tumpang tindih.

  • "Perlu waktu lama untuk menggabungkan permintaan pull untuk dokumentasi orientasi karena kami tidak memiliki panduan yang jelas tentang gaya. Peninjau menunda peninjauan PR karena mereka tidak tahu apa yang harus dilakukan, atau mereka kembali berinteraksi dengan kontributor terkait pemformatan."
  • "Pengguna harus membuka masalah karena mereka tidak dapat menemukan informasi tentang kode error dalam dokumentasi."
  • "Pengujian CI/CD kami gagal karena kami menghadapi batasan paket dan waktu tunggu dari penyedia kami."
  • "Orang-orang kesal dalam rapat mingguan kami karena rapat diadakan pada pukul 05.30 di zona waktu mereka."

Usulkan solusi

Apakah masalah ini dapat diselesaikan dengan dokumentasi baru atau yang lebih baik?

  • "Jika kami memiliki panduan gaya, committer dapat memeriksanya sebelum mengirimkan PR mereka. Peninjau tahu apa yang harus diperiksa. Peninjau dan kontributor tidak perlu berdebat tentang pemformatan, nuansa, dan gaya."
  • "Jika kami memiliki dokumentasi kode error, pengguna dapat menemukan jawaban di sana, bukan membuka masalah."
  • "Hmm, sepertinya dokumentasi yang lebih baik tidak akan memecahkan masalah CI/CD kita."
  • "Kita bisa memulai setiap pertemuan dengan lelucon kasar! Membuat koleksi lelucon "tok-tok" akan membantu kami memulai pertemuan dengan senyum."

Harus spesifik

Bisakah Anda mengukur masalahnya?

  • "Apa yang dimaksud dengan 'memakan 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 'terlalu banyak masalah'?"
  • "Hmmm... seberapa kesalnya 'terlalu kesal'?"

Memeriksa keterukuran

Bagaimana cara memeriksa metrik yang diusulkan? Bisakah itu diukur dengan mudah dan akurat? Apakah pengukuran tergantung pada siapa yang melakukan pengukuran?

  • "Kami dapat dengan mudah mengukur berapa lama permintaan pull telah dibuka, dan berapa lama sejak peninjauan diminta. Kami tidak bisa benar-benar mengukur dengan tepat kapan seorang kontributor menyerah."
  • "Kita dapat menghitung berapa banyak masalah yang diberi tag 'error-code' atau mencari teks kode error dalam masalah."
  • "Kami tidak bisa benar-benar mengukur kecemasan orang dengan cara yang bijaksana atau akurat."

Menambahkan metrik sekunder

Apakah ada metrik lain yang akan membantu Anda memahami apakah dokumentasi tersebut menyelesaikan masalah Anda? Apakah metrik target Anda sama dalam setiap kasus?

  • "Peninjauan PR yang lebih lama membutuhkan waktu lebih lama; kita harus memiliki batas yang berbeda untuk ukuran PR yang berbeda. Kami ingin mengukur waktu penggabungan untuk PR kecil, menengah, besar, dan raksasa."
  • "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

  • "Menurut kami, dua minggu adalah waktu yang wajar untuk menggabungkan PR kecil-ke-menengah; dan semua PR sebaiknya digabungkan dalam waktu satu bulan. Jadi kami akan mengukurnya setiap dua minggu."
  • "Tidak masuk akal untuk memperbarui jumlah masalah terkait kode error setiap hari, karena biasanya waktu kami untuk menyelesaikan masalah adalah satu minggu. Kami akan mengukurnya setiap minggu."

Tentukan target

Berapa banyak perubahan yang perlu Anda lihat dalam metrik yang Anda pilih untuk mengatakan bahwa proyek itu berhasil? Pertimbangkan untuk menetapkan sasaran kuantitatif untuk metrik yang Anda pilih.

  • "Jika kita mencapai sasaran menutup setiap PR baru dalam waktu kurang dari sebulan, maka itu akan sukses. Jika waktu rata-rata kami untuk menutup PR besar berkurang dua minggu, itu akan sukses besar."
  • "Idealnya, kami tidak akan melihat masalah baru terkait error. Namun, kami akan menganggap project kami berhasil jika membuka 50% masalah terkait error."