مرحبًا حبر! اسمي ليشا، أنا محلل أنظمة لأحد فرق المنتجات في Alfa-Bank. أقوم الآن بتطوير بنك جديد عبر الإنترنت للكيانات القانونية وأصحاب المشاريع الفردية.
وعندما تكون محللًا، خاصة في مثل هذه القناة، لا يمكنك الوصول إلى أي مكان دون التوثيق والعمل الوثيق معها. والتوثيق هو الشيء الذي يثير دائمًا الكثير من الأسئلة. لماذا لم يتم وصف تطبيق الويب؟ لماذا تشير المواصفات إلى كيفية عمل الخدمة، لكنها لا تعمل بهذه الطريقة على الإطلاق؟ لماذا لا يستطيع فهم المواصفات سوى شخصين كتبهما أحدهما؟
ومع ذلك، لا يمكن تجاهل التوثيق لأسباب واضحة. ولجعل حياتنا أسهل، قررنا تقييم جودة التوثيق. كيف فعلنا هذا بالضبط وما هي الاستنتاجات التي توصلنا إليها أقل من الخفض.
جودة التوثيق
لكي لا أكرر "بنك الإنترنت الجديد" عشرات المرات في النص، سأكتب بنك الاستثمار القومي. لدينا الآن أكثر من عشرة فرق تعمل على تطوير بنك الاستثمار القومي لرواد الأعمال والكيانات القانونية. علاوة على ذلك، يقوم كل واحد منهم إما بإنشاء وثائقه الخاصة لخدمة جديدة أو تطبيق ويب من البداية، أو إجراء تغييرات على الخدمة الحالية. مع هذا النهج، هل يمكن أن تكون الوثائق ذات جودة عالية من حيث المبدأ؟
ولتحديد جودة التوثيق، قمنا بتحديد ثلاث خصائص رئيسية.
- يجب أن تكون كاملة. يبدو هذا وكأنه كابتن إلى حد ما، ولكن من المهم ملاحظة ذلك. يجب أن يصف بالتفصيل جميع عناصر الحل المطبق.
- يجب أن تكون ذات صلة. وهذا يعني أنه يتوافق مع التنفيذ الحالي للحل نفسه.
- يجب أن يكون مفهوما. حتى يفهم الشخص الذي يستخدمه بالضبط كيفية تنفيذ الحل.
للتلخيص - وثائق كاملة وحديثة ومفهومة.
Опрос
لتقييم جودة الوثائق، قررنا إجراء مقابلات مع أولئك الذين يعملون معها مباشرة: محللو بنك الاستثمار القومي. طُلب من المشاركين تقييم 10 عبارات وفقًا لمخطط "على مقياس من 1 إلى 5 (لا أوافق تمامًا - أوافق تمامًا)."
تعكس البيانات خصائص التوثيق النوعي ورأي القائمين على الدراسة الاستقصائية فيما يتعلق بوثائق بنك الاستثمار القومي.
- الوثائق الخاصة بتطبيقات NIB محدثة ومتسقة تمامًا مع تنفيذها.
- تم توثيق تنفيذ تطبيقات NIB بالكامل.
- التوثيق لتطبيقات NIB مطلوب فقط من أجل الدعم الوظيفي.
- وثائق طلبات NIB محدثة في وقت تقديمها للحصول على الدعم الوظيفي.
- يستخدم مطورو تطبيقات NIB الوثائق لفهم ما يحتاجون إلى تنفيذه.
- توجد وثائق كافية لتطبيقات NIB لفهم كيفية تنفيذها.
- أقوم على الفور بتحديث الوثائق الخاصة بمشاريع NIB إذا تم الانتهاء منها (من قبل فريقي).
- يقوم مطورو تطبيقات NIB بمراجعة الوثائق.
- لدي فهم واضح لكيفية إعداد الوثائق لمشاريع بنك الاستثمار القومي.
- أفهم متى يجب كتابة/تحديث الوثائق الخاصة بمشاريع NIB.
ومن الواضح أن مجرد الإجابة بـ«من 1 إلى 5» قد لا يكشف عن التفاصيل الضرورية، فيمكن للشخص أن يترك تعليقاً على كل عنصر.
لقد فعلنا كل هذا من خلال شركة Slack - لقد أرسلنا ببساطة دعوة لمحللي النظام لإجراء استطلاع. كان هناك 15 محللاً (9 من موسكو و6 من سانت بطرسبرغ). بعد الانتهاء من الاستطلاع، حصلنا على متوسط الدرجات لكل من العبارات العشرة، والتي قمنا بعد ذلك بتوحيدها.
إليكم ما حدث.
أظهر الاستطلاع أنه على الرغم من أن المحللين يميلون إلى الاعتقاد بأن تنفيذ تطبيقات NIB موثق بالكامل، إلا أنهم لا يعطون موافقة لا لبس فيها (0.2). وكمثال محدد، أشاروا إلى أن عددًا من قواعد البيانات وقوائم الانتظار من الحلول الحالية لم يتم تغطيتها بالوثائق. المطور قادر على إخبار المحلل أنه لم يتم توثيق كل شيء. لكن الأطروحة القائلة بأن المطورين يقومون بمراجعة الوثائق أيضًا لم تتلق دعمًا لا لبس فيه (0.33). وهذا يعني أن خطر الوصف غير الكامل للحلول المنفذة لا يزال قائما.
الملاءمة أسهل - على الرغم من عدم وجود اتفاق واضح مرة أخرى (0,13)، لا يزال المحللون يميلون إلى اعتبار الوثائق ذات صلة. أتاحت لنا التعليقات أن نفهم أن المشاكل ذات الصلة بالموضوع تكون في أغلب الأحيان في المقدمة وليس في المنتصف. ومع ذلك، لم يكتبوا لنا أي شيء بشأن الدعم.
أما فيما يتعلق بما إذا كان المحللون أنفسهم يفهمون متى يكون من الضروري كتابة الوثائق وتحديثها، فقد كانت الاتفاقية أكثر اتساقًا (1,33)، بما في ذلك تصميمها (1.07). ما تمت ملاحظته هنا كإزعاج هو عدم وجود قواعد موحدة للحفاظ على الوثائق. لذلك، من أجل عدم تشغيل وضع "من يذهب إلى الغابة، ومن يحصل على الحطب"، يتعين عليهم العمل بناءً على أمثلة الوثائق الموجودة. ومن ثم، فإن الرغبة المفيدة هي إنشاء معيار لإدارة المستندات وتطوير نماذج لأجزائها.
وثائق طلبات NIB محدثة في وقت التقديم للحصول على الدعم الوظيفي (0.73). وهذا أمر مفهوم، لأن أحد معايير تقديم المشروع للحصول على الدعم الوظيفي هو الوثائق الحديثة. ويكفي أيضًا فهم التنفيذ (0.67)، على الرغم من وجود أسئلة في بعض الأحيان.
ولكن ما لم يتفق عليه المشاركون (بالإجماع التام) هو أن التوثيق الخاص بتطبيقات NIB، من حيث المبدأ، ضروري فقط للدعم الوظيفي (-1.53). تم ذكر المحللين في أغلب الأحيان كمستهلكين للوثائق. بقية الفريق (المطورين) - أقل بكثير. علاوة على ذلك، يعتقد المحللون أن المطورين لا يستخدمون الوثائق لفهم ما يحتاجون إلى تنفيذه، وإن لم يكن ذلك بالإجماع (-0.06). وهذا، بالمناسبة، متوقع أيضًا في الظروف التي يتم فيها تطوير التعليمات البرمجية وكتابة الوثائق بالتوازي.
ما هو بيت القصيد ولماذا نحتاج هذه الأرقام؟
لتحسين جودة المستندات، قررنا القيام بما يلي:
- اطلب من المطور مراجعة المستندات المكتوبة.
- إذا أمكن، قم بتحديث الوثائق في الوقت المناسب، للأمام أولاً.
- قم بإنشاء واعتماد معيار لتوثيق مشاريع NIB حتى يتمكن الجميع من فهم عناصر النظام بسرعة وكيف يجب وصفها بالضبط. حسنًا، قم بتطوير القوالب المناسبة.
كل هذا من شأنه أن يساعد في رفع جودة المستندات إلى مستوى جديد.
على الأقل آمل ذلك.
المصدر: www.habr.com