كيف قمنا بتقييم جودة الوثائق

مرحبا يا هبر! اسمي ليشا ، أنا محللة نظام في أحد فرق منتجات Alfa-Bank. الآن أقوم بتطوير بنك إنترنت جديد للكيانات القانونية وأصحاب المشاريع الفردية.

وعندما تكون محللًا ، خاصة في مثل هذه القناة ، بدون وثائق وعمل شاق معها - لا مكان. والوثائق هي الشيء الذي يثير دائمًا الكثير من الأسئلة. لماذا لم يتم وصف تطبيق الويب؟ لماذا تشير المواصفات إلى كيفية عمل الخدمة ، لكنها لا تعمل على الإطلاق؟ لماذا يستطيع شخصان فقط فهم المواصفات ، أحدهما كتبها؟



ومع ذلك ، لا يمكن تجاهل الوثائق لأسباب واضحة. وبغية تبسيط حياتنا ، قررنا تقييم جودة الوثائق. كيف بالضبط فعلنا هذا وما هي النتائج التي توصلنا إليها - تحت الخفض.

جودة الوثائق

من أجل عدم تكرار النص "New Internet Bank" عدة عشرات المرات ، سأكتب NIB. الآن لدينا أكثر من عشرة فرق تعمل على تطوير NIB لأصحاب المشاريع والكيانات القانونية. علاوة على ذلك ، يقوم كل منهم إما من الصفر بإنشاء مستنداته الخاصة بخدمة جديدة أو تطبيق ويب ، أو يقوم بإجراء تغييرات على الخدمة الحالية. مع هذا النهج ، هل يمكن أن تكون الوثائق من حيث المبدأ عالية الجودة؟

ولتحديد جودة الوثائق ، حددنا ثلاث خصائص رئيسية.

1. يجب أن يكون كاملا. يبدو كابتن جميلة ، ولكن من المهم أن نلاحظ. يجب أن تصف بالتفصيل جميع عناصر الحل المطبق.
2. يجب أن تكون ذات صلة. وهذا هو ، تتوافق مع التنفيذ الحالي للحل نفسه.
3. يجب أن يكون واضحا. بحيث يفهم الشخص الذي يستخدمه كيف يتم تنفيذ الحل.

تلخيص - وثائق كاملة وذات صلة ومفهومة.

مقابلة

لتقييم جودة الوثائق ، قررنا إجراء مقابلات مع أولئك الذين يعملون معها مباشرة: محللو بنك الاستثمار القومي. طُلب من المشاركين تقييم 10 بيانات وفقًا للمخطط "على مقياس تقييم من 1 إلى 5 (لا أوافق تمامًا - أوافق تمامًا)".

عكست الادعاءات خصائص وثائق الجودة ورأي مجمعي الاستطلاع فيما يتعلق بوثائق بنك الاستثمار القومي.

1. الوثائق المتعلقة بتطبيقات بنك الاستثمار القومي وثيقة الصلة ومتسقة تماما مع تنفيذها.
2. تم توثيق تطبيق تطبيقات بنك الاستثمار القومي.
3. هناك حاجة إلى الوثائق على تطبيقات NIB فقط للحصول على الدعم الوظيفي.
4. الوثائق المتعلقة بطلبات بنك الاستثمار القومي وثيقة الصلة في وقت تقديمها للحصول على الدعم الوظيفي.
5. يستخدم مطورو تطبيق NIB الوثائق لفهم ما يحتاجون إلى تنفيذه.
6. وثائق تطبيقات NIB كافية لفهم كيفية تنفيذها.
7. سوف أقوم بتحديث الوثائق الخاصة بمشاريع NIB في الوقت المناسب إذا تم الانتهاء منها (بواسطة فريقي).
8. مطورو تطبيق NIB مراجعة الوثائق.
9. لدي فهم واضح لكيفية توثيق مشاريع NIB.
10. أفهم وقت كتابة / تحديث الوثائق على مشاريع NIB.

من الواضح أن الإجابة ببساطة "من 1 إلى 5" لا يمكن أن تكشف التفاصيل الضرورية ، لذلك يمكن للشخص ترك تعليق على كل عنصر.

لقد فعلنا كل ذلك من خلال Slack للشركة - لقد أرسلنا ببساطة اقتراحًا إلى محللي النظام لإجراء الاستطلاع. كان هناك 15 محللاً (9 من موسكو و 6 من سان بطرسبرج). بعد الانتهاء من المسح ، شكلنا تصنيفًا متوسطًا لكل عبارة من العبارات الـ 10 ، والتي تم تطبيعها بعد ذلك.

هذا ما حدث.



أظهر المسح أنه على الرغم من أن المحللين يميلون إلى الاعتقاد بأن تنفيذ تطبيقات NIB موثقة بالكامل ، إلا أنهم لا يمنحون اتفاقًا واضحًا (0.2). وكمثال ملموس ، أشاروا إلى أن عددًا من قواعد البيانات وقوائم الانتظار من الحلول الحالية لم يتم تغطيتها بالوثائق. المطور قادر على إخبار المحلل بأن ليس كل شيء موثق. لكن أطروحة أن المطورين إجراء مراجعة الوثائق أيضا لم يتلق دعم لا لبس فيه (0.33). وهذا هو ، لا يزال خطر عدم اكتمال أوصاف الحلول المنفذة.

الأمر أسهل من حيث الأهمية - على الرغم من عدم وجود اتفاق صريح مرة أخرى (0.13) ، لا يزال المحللون يميلون إلى اعتبار الوثائق ذات صلة. سمحت لنا التعليقات أن نفهم أنه في كثير من الأحيان توجد مشاكل ذات صلة في المقدمة أكثر من منتصفها. صحيح ، لم يكتبوا أي شيء عن الدعم.

بالنسبة إلى ما إذا كان المحللون أنفسهم يفهمون وقت كتابة الوثائق وتحديثها ، فإن الاتفاقية كانت بالفعل أكثر تجانسًا (1.33) ، بما في ذلك تصميمها (1.07). ما لوحظ أنه إزعاج هنا هو عدم وجود قواعد موحدة للحفاظ على الوثائق. لذلك ، لكي لا تشمل نظام "من في الغابة ، من أجل الحطب" ، يتعين عليهم العمل على أساس أمثلة من الوثائق الموجودة. ومن هنا رغبة مفيدة - لإنشاء معيار للحفاظ على الوثائق ، لتطوير قوالب لأجزائها.

الوثائق المتعلقة بتطبيقات NIB ذات صلة في وقت التسليم للحصول على الدعم الوظيفي (0.73). هذا أمر مفهوم ، لأن أحد الوثائق الخاصة بتسليم المشروع إلى الدعم الوظيفي هو الوثائق الحديثة. كما أنه يكفي لفهم التنفيذ (0.67) ، رغم أنه في بعض الأحيان تبقى الأسئلة.

لكن ما لم يتفق عليه المجيبون (بالإجماع إلى حد ما) هو أن الوثائق المتعلقة بتطبيقات بنك الاستثمار القومي ، من حيث المبدأ ، ضرورية فقط للحصول على الدعم الوظيفي (-1.53). تم ذكر المحللين كمستهلكين للوثائق في أغلب الأحيان. أعضاء الفريق الباقون (المطورين) - أقل كثيرًا. علاوة على ذلك ، يعتقد المحللون أن المطورين لا يستخدمون الوثائق لفهم ما يحتاجون إلى تنفيذه ، ولكن ليس بالإجماع (-0.06). هذا ، بالمناسبة ، متوقع أيضًا في الحالات التي تكون فيها وثائق تطوير التعليمات البرمجية وكتابتها متوازيتين.

ما هي النتيجة ولماذا نحتاج هذه الأرقام

لتحسين جودة المستندات ، قررنا القيام بذلك:

1. اطلب من المطور مراجعة المستندات المكتوبة.
2. إذا كان ذلك ممكنا ، في الوقت المناسب تحديث الوثائق ، الجبهة - في المقام الأول.
3. قم بإنشاء واعتماد معيار لتوثيق مشاريع NIB حتى يتمكن الجميع من فهم عناصر النظام وكيفية وصفها بسرعة. حسنا ، تطوير القوالب المناسبة.

كل هذا من شأنه أن يساعد على رفع جودة الوثائق إلى مستوى جديد.

على الأقل آمل ذلك.