Hello, Habr! Nama saya Lesha, saya seorang penganalisis sistem untuk salah satu pasukan produk Alfa-Bank. Sekarang saya sedang membangunkan bank dalam talian baharu untuk entiti sah dan usahawan individu.
Dan apabila anda seorang penganalisis, terutamanya dalam saluran sedemikian, anda tidak boleh pergi ke mana-mana tanpa dokumentasi dan kerja rapat dengannya. Dan dokumentasi adalah sesuatu yang sentiasa menimbulkan banyak persoalan. Mengapa aplikasi web tidak diterangkan? Mengapakah spesifikasi menunjukkan cara perkhidmatan harus berfungsi, tetapi ia tidak berfungsi seperti itu sama sekali? Mengapa hanya dua orang, salah seorang yang menulisnya, dapat memahami spesifikasinya?
Walau bagaimanapun, dokumentasi tidak boleh diabaikan atas sebab yang jelas. Dan untuk menjadikan hidup kami lebih mudah, kami memutuskan untuk menilai kualiti dokumentasi. Seberapa tepat kami melakukan ini dan kesimpulan yang kami buat adalah di bawah pemotongan.
Kualiti dokumentasi
Untuk tidak mengulangi "Bank Internet Baharu" beberapa dozen kali dalam teks, saya akan menulis NIB. Kini kami mempunyai lebih daripada sedozen pasukan yang bekerja pada pembangunan NIB untuk usahawan dan entiti undang-undang. Lebih-lebih lagi, setiap daripada mereka sama ada mencipta dokumentasi sendiri untuk perkhidmatan baharu atau aplikasi web dari awal, atau membuat perubahan pada yang semasa. Dengan pendekatan ini, adakah dokumentasi pada dasarnya boleh berkualiti tinggi?
Dan untuk menentukan kualiti dokumentasi, kami telah mengenal pasti tiga ciri utama.
- Ia mesti lengkap. Ini kedengaran agak seperti kapten, tetapi penting untuk diperhatikan. Ia harus menerangkan secara terperinci semua elemen penyelesaian yang dilaksanakan.
- Ia mesti relevan. Iaitu, sesuai dengan pelaksanaan semasa penyelesaian itu sendiri.
- Ia harus difahami. Supaya orang yang menggunakannya memahami dengan tepat bagaimana penyelesaian itu dilaksanakan.
Untuk meringkaskan - dokumentasi yang lengkap, terkini dan boleh difahami.
Wawancara
Untuk menilai kualiti dokumentasi, kami memutuskan untuk menemu bual mereka yang bekerja secara langsung dengannya: Penganalisis NIB. Responden diminta menilai 10 pernyataan mengikut skema "Pada skala dari 1 hingga 5 (sangat tidak setuju - benar-benar setuju)."
Kenyataan tersebut mencerminkan ciri-ciri dokumentasi kualitatif dan pendapat penyusun tinjauan mengenai dokumen NIB.
- Dokumentasi untuk permohonan NIB adalah terkini dan konsisten sepenuhnya dengan pelaksanaannya.
- Pelaksanaan aplikasi NIB didokumenkan sepenuhnya.
- Dokumentasi untuk aplikasi NIB diperlukan hanya untuk sokongan berfungsi.
- Dokumentasi untuk aplikasi NIB adalah terkini pada masa penyerahan mereka untuk sokongan berfungsi.
- Pembangun aplikasi NIB menggunakan dokumentasi untuk memahami perkara yang mereka perlu laksanakan.
- Terdapat dokumentasi yang mencukupi untuk aplikasi NIB untuk memahami cara ia dilaksanakan.
- Saya segera mengemas kini dokumentasi mengenai projek NIB jika ia dimuktamadkan (oleh pasukan saya).
- Pemaju aplikasi NIB menyemak dokumentasi.
- Saya mempunyai pemahaman yang jelas tentang cara menyediakan dokumentasi untuk projek NIB.
- Saya faham bila hendak menulis/mengemas kini dokumentasi untuk projek NIB.
Adalah jelas bahawa hanya menjawab "Dari 1 hingga 5" mungkin tidak mendedahkan butiran yang diperlukan, jadi seseorang boleh meninggalkan komen pada setiap item.
Kami melakukan semua ini melalui Slack korporat - kami hanya menghantar jemputan kepada penganalisis sistem untuk membuat tinjauan. Terdapat 15 penganalisis (9 dari Moscow dan 6 dari St. Petersburg). Selepas tinjauan selesai, kami menjana skor purata bagi setiap satu daripada 10 penyata, yang kemudiannya kami standardkan.
Inilah yang berlaku.
Tinjauan menunjukkan bahawa walaupun penganalisis cenderung untuk mempercayai bahawa pelaksanaan aplikasi NIB didokumenkan sepenuhnya, mereka tidak memberikan persetujuan yang jelas (0.2). Sebagai contoh khusus, mereka menunjukkan bahawa beberapa pangkalan data dan baris gilir daripada penyelesaian sedia ada tidak diliputi oleh dokumentasi. Pembangun dapat memberitahu penganalisis bahawa tidak semuanya didokumenkan. Tetapi tesis bahawa pemaju menyemak dokumentasi juga tidak menerima sokongan yang tidak berbelah bahagi (0.33). Iaitu, risiko penerangan yang tidak lengkap mengenai penyelesaian yang dilaksanakan kekal.
Perkaitan lebih mudah - walaupun sekali lagi tiada persetujuan yang jelas (0,13), penganalisis masih cenderung untuk mempertimbangkan dokumentasi yang relevan. Komen tersebut membolehkan kami memahami bahawa masalah berkaitan lebih kerap berlaku di hadapan berbanding di tengah. Walau bagaimanapun, mereka tidak menulis apa-apa kepada kami tentang sokongan.
Sama ada penganalisis sendiri memahami apabila perlu untuk menulis dan mengemas kini dokumentasi, perjanjian itu lebih seragam (1,33), termasuk reka bentuknya (1.07). Apa yang dinyatakan di sini sebagai kesulitan adalah kekurangan peraturan seragam untuk mengekalkan dokumentasi. Oleh itu, untuk tidak menghidupkan mod "Siapa yang pergi ke hutan, siapa yang dapat kayu api", mereka perlu bekerja berdasarkan contoh dokumentasi sedia ada. Oleh itu, hasrat yang berguna adalah untuk mencipta standard untuk pengurusan dokumen dan membangunkan templat untuk bahagian mereka.
Dokumentasi untuk aplikasi NIB adalah terkini pada masa penyerahan untuk sokongan berfungsi (0.73). Ini boleh difahami, kerana salah satu kriteria untuk menyerahkan projek untuk sokongan berfungsi ialah dokumentasi terkini. Ia juga mencukupi untuk memahami pelaksanaan (0.67), walaupun kadang-kadang soalan kekal.
Tetapi apa yang responden tidak bersetuju (secara sebulat suara) ialah dokumentasi untuk aplikasi NIB, pada dasarnya, hanya diperlukan untuk sokongan berfungsi (-1.53). Penganalisis paling kerap disebut sebagai pengguna dokumentasi. Selebihnya pasukan (pembangun) - lebih jarang. Selain itu, penganalisis percaya bahawa pembangun tidak menggunakan dokumentasi untuk memahami perkara yang mereka perlu laksanakan, walaupun tidak sebulat suara (-0.06). Ini, dengan cara ini, juga dijangka dalam keadaan di mana pembangunan kod dan penulisan dokumentasi diteruskan secara selari.
Apakah garis bawah dan mengapa kita memerlukan nombor ini?
Untuk meningkatkan kualiti dokumen, kami memutuskan untuk melakukan perkara berikut:
- Minta pembangun menyemak dokumen bertulis.
- Jika boleh, kemas kini dokumentasi tepat pada masanya, depan dahulu.
- Cipta dan pakai piawaian untuk mendokumentasikan projek NIB supaya semua orang dapat memahami dengan cepat elemen sistem yang mana dan bagaimana sebenarnya harus diterangkan. Nah, bangunkan templat yang sesuai.
Semua ini sepatutnya membantu meningkatkan kualiti dokumen ke tahap yang baharu.
Sekurang-kurangnya saya berharap begitu.
Sumber: www.habr.com