توثيق البرمجيات: أنواعها وأفضل الطرق المتّبعة في منهجية أجايل الرشيقة

كتبت بواسطة Ahmad Ali | بتاريخ الأحد 13 أيلول 2020


التوثيق في هندسة البرمجيات هو المصطلح الذي يشمل توفير جميع الوثائق والمواد المكتوبة التي تتعامل مع تطوير منتج برمجي واستخدامه. تتطلب جميع المنتجات البرمجية ، سواء تم إنشاؤها بواسطة فريق صغير أو شركة كبيرة ، بعض الوثائق البرمجية. ويتم إنشاء أنواع مختلفة من المستندات خلال دورة حياة تطوير البرامج بالكامل  Software Development Life Cycle) (SDLC). 


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


التوثيق البرمجي في نهج الشلال والنهج الرشيق 


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


النهج الشلال Waterfall


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

 تسعى فرق Waterfall إلى إنشاء وثائق مفصلة قبل بدء أي من المراحل الهندسية. التخطيط الدقيق والجيد للمشاريع في هذا النهج ينتج عنه القليل من التغييرات إن كان تغيير في الوقت المقّدر للتسليم او تغيير في الكلفة, و بدون هذا التخطيط الجيد لن يتم تقديم  تقديرات دقيقة للميزانية والوقت. ومع ذلك ، فقد ثبت أن تخطيط الشلال غير فعال للتنمية طويلة المدى لأنه لا يأخذ في الحسبان التغيرات المحتملة والطوارئ أثناء المضي في تطوير المنتج البرمجي. وفقًا لاستبيان PMI العالمي التاسع لإدارة المشاريع ، يتم استخدام النهج الرشيق Agile من قبل 71 بالمائة من المؤسسات لمشاريعهم.

تستطيع الإطلاع على النهج الرشيق في مقالة أخرى على مدونة شمرا على الرابط التالي: المنهجية الرشيقة Agile و السكرام Scrum في بناء البرمجيات وإدارة المشاريع.


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

يعد Agile اليوم المنهجية الأكثر شيوعًا في تطوير البرمجيات هذه الأيام، لذلك سنركز على التوثيق البرمجي في المنهجية الرشيقة في هذه المقالة.


أنواع التوثيق البرمجي

الهدف الرئيسي من التوثيق الناجح هو التأكد من أن المطورين والزبون يسيرون في نفس الاتجاه لتحقيق أهداف المشروع ولديهم نفس التوقعات.


التوثيق البرمجي في المنهج الرشيق


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

  • وثائق المنتج Product
  • وثائق العملية Process


وثائق المنتج في المنهج الرشيق

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

  • وثائق النظام
  • وثائق المستخدم


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


وثائق العملية في المنهج الرشيق

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


وثائق النظام

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


وثيقة المتطلبات في المنهج الرشيق

يوفر مستند المتطلبات معلومات حول وظائف النظام. المتطلبات هي الوصف الدقيق لما يجب أن يفعله النظام. يحتوي على قواعد عمل وقصص مستخدمين وحالات استخدام وغيرها. يجب أن يكون هذا المستند واضحًا وبسيطاً. يجب أن يحتوي أيضا على ما يكفي من الوصف الذي يحدد الغرض من المنتج وميزاته ووظائفه وسلوكه.

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

 


هذا القالب تم تطويره من قبل شركة Atlassian

فيما يلي التوصيات الاساسية التي يجب اتباعها عند كتابة هذه الوثيقة:

  1. الأدوار والمسؤوليات . ابدأ المستند بالمعلومات حول المشاركين في المشروع بما في ذلك مالك المنتج وأعضاء الفريق والزبون. ستوضح هذه التفاصيل المسؤوليات وقنوات التواصل المطلوبة.
  2. أهداف الفريق وهدف العمل . حدد أهم الأهداف في صورة نقاط قصيرة.
  3. الخلفية والملاءمة الاستراتيجية . قدم شرحًا موجزًا ​​عن الهدف الاستراتيجي لقراراتك. لماذا تقوم ببناء المنتج؟ كيف تؤثر أفعالك على تطوير المنتج وتتوافق مع أهداف الشركة؟
  4. الافتراضات. قم بإنشاء قائمة بالافتراضات الفنية أو التجارية التي قد تكون لدى الفريق.
  5. قصص المستخدم. سرد أو ربط قصص المستخدم المطلوبة للمشروع. قصة المستخدم هي مستند مكتوب من وجهة نظر شخص يستخدم منتجك البرمجي. قصة المستخدم هي وصف موجز لإجراءات العملاء والنتائج التي يريدون تحقيقها.
  6. تفاعل المستخدم والتصميم.
  7. أسئلة. نظرًا لأن الفريق يحل المشكلات بشكل مستمر، فإن الفريق حتما سيواجه العديد من الأسئلة. من الممارسات الجيدة تسجيل كل هذه الأسئلة وتتبعها.
  8. لا تفعل. ضع قائمة بالأشياء التي لا تفعلها الآن ولكن تخطط للقيام بها قريبًا. ستساعدك هذه القائمة على تنظيم عملك الجماعي وتحديد أولويات المزايا التي سيتم اضافتها للمشروع لاحقا.



اجعل كل هذه المعلومات أكثر شمولية باتباع مايلي:

  • استخدم الروابط التشعبية داخل المستند أو روابط إلى معلومات خارج المستند سوف يساعدك ذلك في تسهيل قراءة المستند والبحث فيه حيث سيتمكن القراء من فهم المعلومات تدريجيًا. على سبيل المثال ، يمكنك توفير روابط لمقابلات مع العملاء وملخصات للنقاشات السابقة أو معلومات خارجية أخرى تتعلق بالمشروع.
  • استخدم أدوات الرسم التخطيطي لتوصيف المشكلة بشكل أفضل للفريق. يميل الأشخاص إلى إدراك المعلومات من خلال النظر إلى الصور أكثر من قراءة مستند شامل. ستساعدك  المخططات المختلفة على أداء هذه المهمة وتحديد المتطلبات بشكل أكثر فعالية. يمكنك دمج المخططات في عملية المتطلبات الخاصة بك باستخدام أدوات الرسم التخطيطي للبرامج التالية: Visio أوDraw IO .

 


نصائح عامة أثناء توثيق البرمجيات
اكتب ما يكفي من الوثائق

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

التوثيقا البرمجي هو عملية مستمرة

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


التوثيق البرمجي هو جهد تعاوني ومسؤولية على عاتق كامل الفريق

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


وظف كاتبًا تقنيًا

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



خلاصة

تُشجّع منهجية أجايل الرشيقة فريق هندسة البرمجيات على التركيز دائمًا على تقديم قيمة مضافة لزبائن الشركة. يجب أيضًا مراعاة هذا المبدأ الأساسي في عملية إنتاج توثيق البرامج. يجب توفير وثائق برمجية جيدة سواء كانت وثيقة مواصفات للمبرمجين والمختبرين أو كتيبات البرامج للمستخدمين النهائيين.