Halo, Habr! Nama saya Lesha, saya seorang analis sistem di salah satu tim produk Alfa-Bank. Sekarang saya sedang mengembangkan bank Internet baru untuk badan hukum dan pengusaha perorangan.
Dan ketika Anda seorang analis, terutama di saluran seperti itu, tanpa dokumentasi dan kerja keras dengannya - tidak ada tempat. Dan dokumentasi adalah hal yang selalu menimbulkan banyak pertanyaan. Mengapa aplikasi web tidak dijelaskan? Mengapa spesifikasi menunjukkan bagaimana layanan harus bekerja, tetapi tidak berfungsi sama sekali? Mengapa hanya dua orang yang bisa memahami spesifikasinya, salah satunya menulisnya?
Namun, dokumentasi tidak dapat diabaikan karena alasan yang jelas. Dan untuk menyederhanakan hidup kami, kami memutuskan untuk menilai kualitas dokumentasi. Bagaimana tepatnya kami melakukan ini dan kesimpulan apa yang kami dapatkan - di bawah potongan.
Kualitas Dokumentasi
Agar tidak mengulangi teks "Bank Internet Baru" beberapa lusin kali, saya akan menulis NIB. Sekarang kami memiliki lebih dari selusin tim yang bekerja pada pengembangan NIB untuk pengusaha dan badan hukum. Selain itu, masing-masing dari awal membuat dokumentasi sendiri untuk layanan atau aplikasi web baru, atau membuat perubahan pada yang sekarang. Dengan pendekatan ini, bisakah pada prinsipnya dokumentasi berkualitas tinggi?
Dan untuk menentukan kualitas dokumentasi, kami mengidentifikasi tiga karakteristik utama.
- Itu harus lengkap. Kedengarannya cukup kapten, tetapi penting untuk diperhatikan. Ini harus menjelaskan secara rinci semua elemen dari solusi yang diterapkan.
- Itu harus relevan. Artinya, sesuai dengan implementasi saat ini dari solusi itu sendiri.
- Itu harus jelas. Sehingga orang yang menggunakannya memahami bagaimana solusi diimplementasikan.
Meringkas - dokumentasi yang lengkap, relevan dan dapat dimengerti.
Polling
Untuk menilai kualitas dokumentasi, kami memutuskan untuk mewawancarai mereka yang bekerja secara langsung dengannya: analis NIB. Responden diminta untuk menilai 10 pernyataan sesuai dengan skema "Pada skala 1 sampai 5 (sama sekali tidak setuju - sepenuhnya setuju)".
Tuduhan tersebut mencerminkan karakteristik dokumentasi kualitas dan pendapat para penyusun survei mengenai dokumen NIB.
- Dokumentasi tentang aplikasi NIB relevan dan sepenuhnya konsisten dengan implementasinya.
- Implementasi aplikasi NIB sepenuhnya didokumentasikan.
- Dokumentasi pada aplikasi NIB hanya diperlukan untuk dukungan fungsional.
- Dokumentasi pada aplikasi NIB relevan pada saat pengajuannya untuk dukungan fungsional.
- Pengembang aplikasi NIB menggunakan dokumentasi untuk memahami apa yang perlu mereka terapkan.
- Dokumentasi untuk aplikasi NIB cukup untuk memahami bagaimana mereka diterapkan.
- Saya akan memperbarui dokumentasi tentang proyek NIB tepat waktu jika proyek tersebut selesai (oleh tim saya).
- Dokumentasi ulasan pengembang aplikasi NIB.
- Saya memiliki pemahaman yang jelas tentang bagaimana mendokumentasikan proyek NIB.
- Saya mengerti kapan harus menulis / memperbarui dokumentasi tentang proyek NIB.
Jelas bahwa jawaban "Dari 1 hingga 5" tidak dapat mengungkapkan detail yang diperlukan, sehingga seseorang dapat meninggalkan komentar pada setiap item.
Kami melakukan semua ini melalui Slack perusahaan - kami hanya mengirim proposal ke analis sistem untuk mengikuti survei. Ada 15 analis (9 dari Moskow dan 6 dari St. Petersburg). Setelah survei selesai, kami membentuk peringkat rata-rata untuk masing-masing dari 10 pernyataan, yang kemudian dinormalisasi.
Inilah yang terjadi.
Survei menunjukkan bahwa meskipun analis cenderung percaya bahwa implementasi aplikasi NIB sepenuhnya didokumentasikan, mereka tidak memberikan kesepakatan yang jelas (0,2). Sebagai contoh nyata, mereka menunjukkan bahwa sejumlah database dan antrian dari solusi yang ada tidak tercakup oleh dokumentasi. Pengembang dapat memberi tahu analis bahwa tidak semuanya didokumentasikan. Tetapi tesis bahwa pengembang melakukan review dokumentasi juga tidak menerima dukungan yang jelas (0,33). Yaitu, risiko deskripsi yang tidak lengkap dari solusi yang diterapkan tetap ada.
Lebih mudah dengan relevansi - meskipun tidak ada perjanjian tegas lagi (0,13), analis masih cenderung untuk mempertimbangkan dokumentasi yang relevan. Komentar memungkinkan kami untuk memahami bahwa lebih sering ada masalah dengan relevansi di depan daripada di tengah. Benar, mereka tidak menulis apa pun tentang dukungan.
Seperti apakah para analis sendiri mengerti kapan harus menulis dan memperbarui dokumentasi, perjanjian itu sudah jauh lebih seragam (1,33), termasuk desainnya (1,07). Apa yang dicatat sebagai ketidaknyamanan di sini adalah kurangnya aturan yang seragam untuk menjaga dokumentasi. Oleh karena itu, agar tidak memasukkan rezim “Siapa yang di hutan, siapa yang untuk kayu bakar”, mereka harus bekerja berdasarkan contoh-contoh dokumentasi yang ada. Karenanya harapan yang berguna - untuk membuat standar untuk memelihara dokumen, untuk mengembangkan template untuk bagian-bagiannya.
Dokumentasi pada aplikasi NIB relevan pada saat pengiriman untuk dukungan fungsional (0,73). Dapat dimengerti, karena salah satu kriteria untuk menyerahkan proyek kepada dukungan fungsional adalah dokumentasi terbaru. Juga cukup untuk memahami implementasinya (0,67), meskipun terkadang masih ada pertanyaan.
Tetapi apa yang tidak disetujui oleh responden (agak bulat) adalah bahwa dokumentasi pada aplikasi NIB, pada prinsipnya, hanya diperlukan untuk dukungan fungsional (-1.53). Analis sebagai konsumen dokumentasi disebutkan paling sering. Anggota tim yang tersisa (pengembang) - lebih jarang. Selain itu, analis percaya bahwa pengembang tidak menggunakan dokumentasi untuk memahami apa yang perlu mereka terapkan, meskipun tidak dengan suara bulat (-0,06). Omong-omong, ini juga diharapkan dalam kondisi ketika pengembangan kode dan dokumentasi penulisan berjalan paralel.
Apa hasilnya dan mengapa kita membutuhkan angka-angka ini
Untuk meningkatkan kualitas dokumen, kami memutuskan untuk melakukan ini:
- Minta pengembang untuk meninjau dokumen tertulis.
- Jika mungkin, perbarui dokumentasi tepat waktu, bagian depan - di tempat pertama.
- Membuat dan mengadopsi standar untuk mendokumentasikan proyek-proyek NIB sehingga setiap orang dapat dengan cepat memahami elemen mana dari sistem dan bagaimana menggambarkannya. Nah, kembangkan templat yang sesuai.
Semua ini akan membantu meningkatkan kualitas dokumen ke tingkat yang baru.
Setidaknya saya harap begitu.