دراسات ميدانية لمفهوم "التوثيق كرمز"

مرحبا بالجميع! اسمي دينيس أولينيك ، أعمل كمدير فني في 1Service.

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

هذا الخط يقع في مكان ما بين المتطلبات المسجلة في التقاء ومهام تنفيذها في جيرا. ينتقل سطر آخر بين حالات الاختبار في أداة الاختبار ونفس المتطلبات في Confluence ، مع التركيز على الكود المرتبط بالمهام في Jira. عدم وجود إجابات واضحة على الأسئلة: "لماذا / لماذا فعلنا ذلك بهذه الطريقة" أو "هل فعلنا كل ما يريده العميل منا" - تسبب لنا في قلق شديد.

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

الشروط

في رأينا ، ما يوقف الاستخدام الواسع النطاق لهذا المفهوم بين الجماهير هو بؤس الأدوات اللازمة للتمثيل المرئي وإدارة المتطلبات في شكل نص مسطح. هذا يعني أنك لن تعرض الملفات النصية المسطحة "مالك المنتج" بحيث يرى Project Scope فيها ، ولا يمكنك عرض الملفات النصية على صفحة العرض التقديمي لأصحاب المصلحة ، وليس لديهم رسومات بيانية ومخططات وصور في مرحلة التحرير - وهذا مثير للاشمئزاز بالفعل والتي يجب أن تولد أساسا المحتوى. فقط المطورين سعداء ويصرخون: "رائع! المتشددين فقط! أكثر يرتكب! "وغيرها من بدعة.

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

حسنًا ، نعم - أولاً ، إنها "غير ملائمة ، حبيبة ، جافة" ، وثانياً ، تغطي الرقائق الفنية مشكلة تحديث الوثائق بقطعة قماش. هناك صورة نمطية شائعة: "نحن عن طريق ajail - لكننا لسنا بحاجة إلى وثائق في ajail!" بعبارة ملطفة ، هذا ليس صحيحًا تمامًا. أرغب في دحض هذا الخطأ من خلال مقارنة نهج استخدام حالة المستخدم وقصة المستخدم من كتاب Karl Wigers الممتاز "تطوير متطلبات البرامج" [4]. إذا قمنا بربط مناهج التطوير القائمة على قصص المستخدم بمنهجية Agile ، فحينها تقوم Wigers بصياغة تطور المتطلبات على أساس قصص المستخدم بهذه الطريقة:

سجل المستخدم → (المناقشات) → تاريخ المستخدم المحدث (مع معايير القبول) → (المناقشات) → اختبارات القبول

(ص 169 ، الشكل 8-1). وبالتالي ، فإن وثائق الإخراج نتيجة لتطور المتطلبات الأولية في مشاريع التطوير الرشيقة هي اختبارات القبول. اليوم ، هناك أسلوب شائع إلى حد ما لتنظيم اختبار القبول وهو استخدام البرامج النصية للاختبار المكتوبة بلغة Gherkin [5] ، المخزنة في ما يسمى ملفات الميزات (بسيطة ، نصية).

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

بنية أداة البحث

لذلك ، لا توجد أداة ، لكنني أريد استكشاف المفهوم. من اليأس ، كان علينا تطويره. إذا كانت هذه الأداة (دعنا نسميها StoryMapper) موجودة بالفعل ، فما نوع العمارة التي ستتمتع بها من أجل الاندماج بشكل غير مزعج ، مع الحد الأدنى من الإجهاد ، في النظام البيئي الحالي لعملية التطوير؟ إذا كانت هذه بالفعل عملية تطوير مضمّنة ، فمن المحتمل أن تكون حلقة CI / CD قيد التشغيل بالفعل ، ومن المؤكد أنه سيتم استخدام نظام التحكم في الإصدار ، على الأرجح على بوابة. في هذه الحالة ، يوضح الرسم البياني أدناه مكان StoryMapper أثناء عملية التطوير:


التين. 1 مكان أداة StoryMapper في بنية عملية التطوير

وبالتالي ، سيتفاعل StoryMapper مباشرة مع خدمات استضافة مستودعات git ومع حلقة CI / CD . يلزم التكامل مع خدمات استضافة git للحصول على المجموعة الحالية من ملفات الميزات (إن وجدت) ، وكذلك لوضع نتائج التغييرات على ملفات الميزات ، وملفات الخدمة ذات الصلة بهيكلة الوثائق ، وأمثلة على بيانات المدخلات والمخرجات مرة أخرى على المستودع ، إلخ. . الخ التفاعل مع CI كفاف / CD حاجة لتكون قادرة على تشغيل اختبار سيناريو التجمع (دليل أو المقرر)، ونتائج اختبار اللاحقة - لمطابقتها مع المقابلة ميزة الملفات (مثل OBRA عشر سيتم التحقق والتحقق من أهمية الوثائق).

عليك أن تفهم أن StoryMapper بالكاد يجب أن يطالب بلقب "محرر Gherkin آخر". نعم ، يجب تحديد القدرة الأساسية على تحرير ملفات الميزات ، لكننا ندرك بوضوح أنه إذا اختارت مكتبة الإسكندرية أو ضمان الجودة VSC أو Sublime أو Notepad ++ أو حتى vi (لماذا لا؟) ، فقم بإقناعهم بالعمل مع المتطلبات فقط في StoryMapper المهمة ليست بالامتنان ، ولكنها غير صحيحة إلى حد ما. لذلك ، نفترض أنه ينبغي وضع إمكانية الاستخدام المتنوع لـ StoryMapper ، على وجه الخصوص: تطوير الميزات في محررك المفضل ، ويتم استخدام StoryMapper في تصميم ملفات الميزات الجاهزة. المزيد حول هذا الموضوع في قسم اتجاهات البحث.

الحد الأدنى المطلوب وظيفة

نظرًا لأن StoryMapper موجود حاليًا في حالة MVP ، فهذه هي الحد الأدنى من المتطلبات التي قطعناها على أنفسنا حتى يمكن البدء في استخدامها:

• رسم خرائط قصة مبنية على بوابة.
• الخيارة محرر.
• إطلاق تجميع اختبار السيناريو (يدويًا ووفقًا للجدول الزمني) ؛
• انعكاس نتائج اختبار السيناريو على خريطة قصص المستخدم.

لن أتطرق إلى وظيفة الأداة ، لأن موضوع هذه المقالة هو سير العملية وليس مشرط الجراح.

مجالات البحث

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

لذلك ، StoryMapper هي أداة ، فهي لا تنظم حالة الاستخدام الحقيقية الوحيدة. على العكس من ذلك ، يمكن لكل مستخدم محتمل رؤية خياراته لاستخدام الأداة. ركزنا على ثلاثة مجالات رئيسية:

• تطوير مرن: من خريطة القصة إلى اختبارات القبول ؛
• هيكلة وتصور مجموعة من ملفات الميزات ؛
• مراقبة الإنتاجية.

فيما يلي سوف أصف بالتفصيل النتائج التي حققناها في كل اتجاه.

تطوير مرن: من بطاقات القصة إلى اختبارات القبول

يتضمن هذا الاتجاه تطوير منتج جديد أو تحسين منتج موجود. تم العمل في هذا الاتجاه تحت الاسم الرمزي "BDDSM": كمزيج من تقنية تعيين الخرائط ومنهجية تطوير BDD . واتخذت الجذر.

لذلك ، بالنسبة للمبتدئين ، يتم إنشاء مستودع git لملفات الميزات ، ويتم تخصيص فرع فيه للتفاعل مع StoryMapper. يتم إنشاء مشروع في StoryMapper ، وهو مرتبط بمحللي الأعمال الذين سيعملون في المشروع. التواصل مع أصحاب المصلحة ، يبدأ محللو الأعمال في صياغة رؤية مشتركة للمنتج وإصلاحه في شكل هيكل عظمي لخريطة قصة المستخدم [١.٢] ، أولًا رسم تخطيطي للمستوى الأول من UF :


التين. 6 الهيكل العظمي المستوى العلوي من خريطة قصص المستخدم (قابلة للنقر)

ثم تملأ تدريجيا المستوى الثاني من أنشطة المستخدم:

التين. 7 الهيكل العظمي المستوى الثاني من خريطة قصص المستخدم

نظرًا لأن كل بطاقة عبارة عن ملف نصي ، إما في مرحلة تجميع المتطلبات (إذا تم تجميع البطاقة في سياق التواصل مع المستخدم) ، أو في مرحلة ما بعد المعالجة للمقابلات ، يتم نقل نتائج الاتصال مباشرة إلى بطاقات UF و UA . هذا هو الأساس لمزيد من التحلل من المتطلبات لمستوى قصص المستخدم.


التين. 8 متطلبات Gherkin بناء جملة خالية النص على مستوى UF

بعد ذلك ، يدرك محللو الأعمال كيفية تقسيم أنشطة المستخدم إلى قصص المستخدمين ، وتشكيل مستوى خريطة ثالث في StoryMapper - الولايات المتحدة . يرتبط عزل الولايات المتحدة بصياغة معايير القبول ، أي إذا كنت "كشخص ما تريد شيئًا ما" ، فسوف نتحقق بعد استلامك لها [3]. يمكن أيضًا تحديد معايير القبول للمبتدئين في الولايات المتحدة كنص ثابت.

بعد وضع معايير القبول والاتفاق عليها مع أصحاب المصلحة ، وضعها محللو الأعمال في شكل نصوص بلغة غيركين. في الواقع ، يتم إلحاق النص "السيناريو: KP-No" بكل معيار قبول ، والذي يحول قصة المستخدم المجردة حتى الآن إلى ملف ميزة.


التين. 8.1 معايير القبول لقصص المستخدم كنصوص على Gherkin

بعد ذلك ، يتم فك تشفير كل سيناريو بعدة خطوات موسعة تكشف كيف سيتم التحقق من معيار القبول المحدد. علاوة على ذلك ، تتم برمجة هذه الخطوات بواسطة المطورين أو كتابتها من مكتبة خطوات إطار عمل Gherkin المستخدم وتصديرها لتصدير البرامج النصية.

بالتوازي مع هذا ، يتم تنظيم مقعد اختبار يقوم عليه خادم التجميع بإجراء اختبارات وظيفية وينتظر الوقت الحالي عندما تكون الولايات المتحدة مع البرامج النصية جاهزة. نظرًا لأن المنتج والسيناريوهات التي تطبق معايير القبول جاهزة ، يبدأ خادم التجميع في إصدار التقارير بتنسيق Allure و Cucumber وإرسالها إلى StoryMapper ، والذي بدوره ينتج عن التجميع ينتج عنه تنسيق Cucumber على خريطة قصة المستخدم:


التين. 9 خريطة قصص المستخدم مع نتائج البرمجة

في الوقت نفسه ، يوفر StoryMapper ثلاثة مستويات لفهم جاهزية المنتج: UF هو المستوى الأعلى الذي يعرض عدد البرامج النصية العاملة بشكل صحيح (تلبية معايير القبول) ، والعمل مع الأخطاء ، وليس جاهزًا بعد. هذا هو ، في الواقع ، المستوى العلوي هو مؤشر على جاهزية المنتج ومؤشر على مقدار ما زال هناك الكثير الذي يتعين القيام به (هذا هو مستوى مالك المنتج). تتيح لك المستويات الأدنى معرفة نوع أنشطة المستخدم التي توجد بها صعوبات بالضبط ، وحيث تحتاج إلى بذل جهود لإنهاء المنتج (وهذا هو مستوى أسياد scrum إلى حد أكبر ومالك المنتج إلى حد أقل). المستوى الأدنى في الولايات المتحدة هو المستوى الذي يتفاعل فيه محللو الأعمال والمطورين وضمان الجودة ، ويطورون بشكل مشترك المنتج الذي يتوقعه أصحاب المصلحة منهم.

أيضًا ، في واحدة من الخطوات النهائية لخط التجميع ، يتم إنشاء التوثيق التلقائي. يمكنك قراءة المزيد حول هذا الموضوع مع الزملاء . ليس هذا هو الخيار الوحيد ، فنحن نخطط لتضمين حزمة Pickles في أداتنا - المعيار الفعلي في عالم "الوثائق المباشرة".

هيكلة وتصور مجموعة من ملفات الميزات

العمل في هذا الاتجاه ، نظرنا في مثل هذه الحالة. قام فريق التطوير ، في أعقاب الضجة حول موضوع BDD والاختبارات الوظيفية ومعايير تطوير الصناعة ، بكتابة ملفات الميزات. وكسر الأشواك ، تراكمت مجموعة كبيرة إلى حد ما في المستودع. ومع ذلك ، عندما يكون لديك 10 ملفات في مجموعتك ، فإن التقرير بتنسيق Allure لا يزال يعطي بعض الصور الموثوقة لحالة المنتج. ولكن إذا تم قياس عدد ملفات الميزات بعشرات ، وفي بعض الأحيان بالمئات ، فأنت عاجلاً أم آجلاً ستحتاج إلى هيكلها بطريقة أو بأخرى. أول ما يتبادر إلى الذهن هو فرزها في مجلدات مواضيعية. ولماذا؟ من قبل أصحاب المصلحة ، من خلال البيانات الوصفية ، من قبل النظم الفرعية؟ هذه هي أبعد ما تكون عن الأسئلة الخاملة. وإذا تبين لاحقًا أن ملفات المعالم قد كتبت في الأصل لأن الله سيضعها في النفوس ، وهناك نصوص مرتبطة بعدة مجلدات في آن واحد ، فكيف؟

لذلك ، تشير حالة الاستخدام هذه إلى الرغبة في تنظيف مستنداتك من أجل التبديل من "ميزات بشكل منفصل ، وثائق منفصلة" إلى "وثائق رمز". عندما يكون هذا المستودع متصلاً بـ StoryMapper ، فستقع جميع ملفات الميزات في العمود الأول تحت UF0 و UA0. والخطوة التالية في الهيكلية هي تكوين الهيكل العظمي للهيكل. في StoryMapper ، كل هذه هي نفس UF و UA ، ولكن لا أحد يصر على النظر فيها فقط من هذه الزاوية. يمكن اعتبارها مجرد مستويين من التسلسل الهرمي ، والذي بموجبه يمكن وضع ملفات ميزات غير منظمة سابقًا. بعد ضبط الهيكل ، يتم سحب ملفات المعالم من العمود الأول تحت UA المقابل. مما لا شك فيه ، أن هذه العملية تتسبب في هجوم على التفكير وإعادة تكوين الميزات ، لأنه أثناء السحب ، يصبح عمق الفوضى الذي حدث أثناء الكتابة الأولية واضحًا. في بعض الأحيان ، يكفي نقل البرنامج النصي من ملف إلى آخر ، وأحيانًا تقسيم ملف كبير إلى عدة ملفات لاستعادة الاتصال الدلالي ، وأحيانًا مجرد إلقاءه في سلة المهملات ، لأن المخطوطات القديمة غير القابلة للتنفيذ كانت في المستودع.

إذا كان قد تم بالفعل تكوين خط التجميع (جيدًا ، نظرًا لوجود مستودع لملفات المعالم ، فيجب تجميعه في مكان ما) ، فأنت بحاجة إلى إضافة خطوة إليه لإرسال نتائج التجميع إلى StoryMapper. ستكون النتيجة النهائية هي الصورة الأخيرة من القسم السابق (الشكل 9): ملفات المعالم المهيكلة مع علامات على نتائج البرامج النصية الخاصة بهم.

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

مراقبة المنتج

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

كما نراها. خيار بسيط: من مجموعة الاختبارات الوظيفية ، يتم تحديد مجموعة فرعية معينة من اختبارات قاعدة البيانات غير المعدلة التي تتحقق من الواجهة الأمامية. : , -, , , -, , . , . StoryMapper Allure, , — , , , IT- .

, , . , , , , - .

, , :

• , ;
• , , ;
• StoryMapper ;
• StoryMapper .

اتجاهات التنمية

, StoryMapper MVP. , « », , , , . , , « ». , :

• « », « — »;
• (, etc. );
• / / Excel;
• - Jira ( , ).

, , , . , .

( ), , ( !) — telegram , .

1. , . , ., , 2017.
2. , . , .-.-, , 2012.
3. Gojko Adjic, Specification by Example, NY, Manning Publication, 2011.
4. , , , .: ; .: -, 2014.
5. BDD «What's in a story»
6. « — » «Write the docs»
7. « — » " docToolchain "