Bagaimana kami menilai kualitas dokumentasi

Halo, Habr! Nama saya Lesha, saya seorang analis sistem di salah satu tim produk Alfa-Bank. Sekarang saya sedang mengembangkan bank online baru untuk badan hukum dan pengusaha perorangan.

Dan bila Anda seorang analis, terutama di saluran seperti itu, Anda tidak akan bisa kemana-mana tanpa dokumentasi dan kerja keras dengannya. Dan dokumentasi merupakan hal yang selalu menimbulkan banyak pertanyaan. Mengapa aplikasi web tidak dijelaskan? Mengapa spesifikasi menunjukkan cara kerja layanan, tetapi tidak berfungsi sama sekali? Mengapa hanya dua orang, salah satunya yang menulisnya, yang dapat memahami spesifikasinya?

Namun, dokumentasi tidak dapat diabaikan karena alasan yang jelas. Dan untuk membuat hidup kami lebih mudah, kami memutuskan untuk mengevaluasi kualitas dokumentasi. Bagaimana sebenarnya kami melakukan hal ini dan kesimpulan apa yang kami dapatkan masih di bawah batas.

Kualitas dokumentasi

Agar tidak mengulangi “Bank Internet Baru” beberapa lusin kali dalam teks, saya akan menulis NIB. Saat ini kami memiliki lebih dari selusin tim yang mengerjakan pengembangan NIB bagi pengusaha dan badan hukum. Selain itu, masing-masing dari mereka membuat dokumentasinya sendiri untuk layanan atau aplikasi web baru dari awal, atau membuat perubahan pada yang sekarang. Dengan pendekatan ini, apakah dokumentasi pada prinsipnya dapat berkualitas tinggi?

Dan untuk menentukan kualitas dokumentasi, kami telah mengidentifikasi tiga karakteristik utama.

1. Itu harus lengkap. Ini terdengar seperti kapten, tetapi penting untuk diperhatikan. Ini harus menjelaskan secara rinci semua elemen dari solusi yang diterapkan.
2. Itu harus terkini. Artinya, sesuai dengan implementasi solusi itu sendiri saat ini.
3. Ini harusnya bisa dimengerti. Sehingga orang yang menggunakannya paham betul bagaimana solusi tersebut diterapkan.

Ringkasnya - dokumentasi yang lengkap, terkini dan mudah dipahami.

Опрос

Untuk menilai kualitas dokumentasi, kami memutuskan untuk mewawancarai mereka yang bekerja langsung dengannya: analis NIB. Responden diminta mengevaluasi 10 pernyataan menurut skema “Pada skala 1 sampai 5 (sangat tidak setuju – sangat setuju).”

Pernyataan tersebut mencerminkan karakteristik dokumentasi kualitatif dan pendapat penyusun survei terhadap dokumen NIB.

1. Dokumentasi permohonan NIB adalah yang terkini dan sepenuhnya konsisten dengan penerapannya.
2. Penerapan permohonan NIB terdokumentasi secara lengkap.
3. Dokumentasi permohonan NIB diperlukan hanya untuk penunjang fungsional.
4. Dokumentasi permohonan NIB terkini pada saat diajukan untuk dukungan fungsional.
5. Pengembang aplikasi NIB menggunakan dokumentasi untuk memahami apa yang perlu mereka terapkan.
6. Terdapat cukup dokumentasi untuk aplikasi NIB untuk memahami cara penerapannya.
7. Saya segera memperbarui dokumentasi proyek NIB jika sudah diselesaikan (oleh tim saya).
8. Pengembang aplikasi NIB meninjau dokumentasi.
9. Saya memiliki pemahaman yang jelas tentang cara menyiapkan dokumentasi untuk proyek NIB.
10. Saya memahami kapan harus menulis/memperbarui dokumentasi untuk proyek NIB.

Jelas bahwa hanya menjawab “Dari 1 sampai 5” mungkin tidak mengungkapkan rincian yang diperlukan, sehingga seseorang dapat memberikan komentar pada setiap item.

Kami melakukan semua ini melalui perusahaan Slack - kami hanya mengirimkan undangan ke analis sistem untuk mengikuti survei. Ada 15 analis (9 dari Moskow dan 6 dari St. Petersburg). Setelah survei selesai, kami menghasilkan skor rata-rata untuk masing-masing dari 10 pernyataan, yang kemudian kami standarkan.

Inilah yang terjadi.

Survei menunjukkan bahwa meskipun para analis cenderung percaya bahwa penerapan permohonan NIB telah didokumentasikan secara lengkap, mereka tidak memberikan persetujuan yang jelas (0.2). Sebagai contoh spesifik, mereka menunjukkan bahwa sejumlah database dan antrian dari solusi yang ada tidak tercakup dalam dokumentasi. Pengembang dapat memberi tahu analis bahwa tidak semuanya didokumentasikan. Namun tesis bahwa pengembang meninjau dokumentasi juga tidak mendapat dukungan tegas (0.33). Artinya, masih ada risiko deskripsi solusi yang diterapkan tidak lengkap.

Relevansi lebih mudah - meskipun sekali lagi tidak ada kesepakatan yang jelas (0,13), analis masih cenderung menganggap dokumentasi tersebut relevan. Komentar tersebut membuat kami memahami bahwa masalah relevansi lebih sering terjadi di bagian depan daripada di tengah. Namun, mereka tidak menulis apa pun kepada kami tentang dukungan.

Mengenai apakah para analis sendiri memahami kapan perlunya menulis dan memperbarui dokumentasi, perjanjian tersebut jauh lebih seragam (1,33), termasuk desainnya (1.07). Apa yang dianggap sebagai ketidaknyamanan di sini adalah kurangnya aturan yang seragam dalam memelihara dokumentasi. Oleh karena itu, agar tidak mengaktifkan mode “Siapa yang ke hutan, siapa yang mendapat kayu bakar”, mereka harus bekerja berdasarkan contoh dokumentasi yang ada. Oleh karena itu, harapan yang berguna adalah menciptakan standar untuk manajemen dokumen dan mengembangkan templat untuk bagian-bagiannya.

Dokumentasi permohonan NIB terkini pada saat pengajuan dukungan fungsional (0.73). Hal ini dapat dimaklumi, karena salah satu kriteria pengajuan proyek untuk dukungan fungsional adalah dokumentasi terkini. Pemahaman terhadap implementasinya juga sudah cukup (0.67), meskipun terkadang masih ada pertanyaan.

Namun yang tidak disetujui oleh responden (dengan suara bulat) adalah bahwa dokumentasi permohonan NIB pada prinsipnya hanya diperlukan untuk penunjang fungsional (-1.53). Analis paling sering disebutkan sebagai konsumen dokumentasi. Anggota tim lainnya (pengembang) - lebih jarang. Selain itu, para analis percaya bahwa pengembang tidak menggunakan dokumentasi untuk memahami apa yang perlu mereka terapkan, meskipun tidak secara bulat (-0.06). Hal ini juga diharapkan dalam kondisi di mana pengembangan kode dan penulisan dokumentasi berlangsung secara paralel.

Apa intinya dan mengapa kita membutuhkan angka-angka ini?

Untuk meningkatkan kualitas dokumen, kami memutuskan untuk melakukan hal berikut:

1. Minta pengembang untuk meninjau dokumen tertulis.
2. Jika memungkinkan, perbarui dokumentasi secara tepat waktu, terlebih dahulu.
3. Membuat dan menerapkan standar untuk mendokumentasikan proyek NIB sehingga setiap orang dapat dengan cepat memahami elemen sistem mana dan bagaimana tepatnya harus dijelaskan. Nah, kembangkan template yang sesuai.

Semua ini akan membantu meningkatkan kualitas dokumen ke tingkat yang baru.

Setidaknya saya berharap demikian.

Sumber: www.habr.com