وثائق البرمجيات

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

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

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

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

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

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

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

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

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

• مصمم قواعد البيانات
• مطور قواعد البيانات
• مسؤول قاعدة البيانات
• مصمم تطبيقات
• مطور التطبيقات

عند الحديث عن أنظمة قواعد البيانات العلائقية ، يجب أن تتضمن الوثيقة الأجزاء التالية:

• مخطط العلاقة بين الكيانات ( سواء كان مُحسَّنًا أم لا)، بما في ذلك المعلومات التالية وتعريفاتها الواضحة:
  • مجموعات الكيانات وخصائصها
  • العلاقات وخصائصها
  • مفاتيح مرشحة لكل مجموعة كيانات
  • القيود القائمة على السمات والصفوف
• مخطط العلاقات، بما في ذلك المعلومات التالية:
  • الجداول والسمات وخصائصها
  • المشاهدات
  • القيود مثل المفاتيح الأساسية والمفاتيح الخارجية،
  • عدد القيود المرجعية
  • سياسة التتالي للقيود المرجعية
  • المفاتيح الأساسية

من المهم للغاية تضمين جميع المعلومات التي سيستخدمها جميع المشاركين في المشهد. كما أنه من المهم للغاية تحديث المستندات عند حدوث أي تغيير في قاعدة البيانات.

من المهم أن تكون وثائق الكود المرتبطة بشفرة المصدر (والتي قد تشمل ملفات README ووثائق واجهة برمجة التطبيقات ( API )) شاملة، ولكن دون الإسهاب المفرط الذي يُعيق صيانتها أو يُطيل وقتها. تتوفر عادةً أدلة إرشادية ووثائق عامة خاصة بتطبيق أو منتج برمجي يُوثّقه مطورو واجهة برمجة التطبيقات . يمكن للمطورين والمختبرين والمستخدمين النهائيين استخدام هذه الوثائق. اليوم، نرى العديد من التطبيقات المتطورة في مجالات الطاقة، والنقل، والشبكات، والفضاء، والسلامة، والأمن، وأتمتة الصناعة، وغيرها من المجالات. أصبحت الوثائق التقنية ذات أهمية بالغة في هذه المؤسسات، حيث قد تتغير المعلومات، سواء الأساسية أو المتقدمة، بمرور الوقت مع تغيرات البنية. وتشير الأدلة إلى أن وجود وثائق جيدة للكود يُقلل من تكاليف صيانة البرمجيات. ^{[ 1 ]}

غالباً ما يتم تنظيم وثائق التعليمات البرمجية على شكل دليل مرجعي ، مما يسمح للمبرمج بالبحث بسرعة عن أي دالة أو فئة.

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

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

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

يمكن إنتاج وثائق المستخدم في مجموعة متنوعة من التنسيقات الإلكترونية والمطبوعة. ^{[ 2 ]} ومع ذلك، يمكن تنظيم وثائق المستخدم بثلاث طرق رئيسية:

1. البرنامج التعليمي – يُعتبر أسلوب البرنامج التعليمي الأكثر فائدة للمستخدم الجديد، حيث يتم توجيهه خلال كل خطوة من خطوات إنجاز المهام المحددة. ^{[ 3 ]}
2. المنهج الموضوعي – يُعدّ المنهج الموضوعي ، حيث تُركّز الفصول أو الأقسام على مجال اهتمام مُحدّد، أكثر فائدةً للمستخدم المتوسط. يُفضّل بعض المؤلفين إيصال الأفكار من خلال مقال قائم على المعرفة لتلبية احتياجات المستخدم. يُمارس هذا المنهج عادةً في قطاع ديناميكي، مثل تكنولوجيا المعلومات . ^{[ 4 ]}
3. القائمة أو المرجع – يتمثل النوع الأخير من مبادئ التنظيم في سرد ​​الأوامر أو المهام أبجديًا أو تجميعها منطقيًا، غالبًا عبر فهارس مرجعية. يُعد هذا الأسلوب الأخير أكثر فائدة للمستخدمين المتقدمين الذين يعرفون تحديدًا نوع المعلومات التي يبحثون عنها.

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

في العديد من التطبيقات، من الضروري توفير بعض المواد الترويجية لتشجيع المشاهدين العاديين على قضاء المزيد من الوقت في التعرف على المنتج. لهذا النوع من التوثيق ثلاثة أغراض:

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

نظام "الوثائق كشفرة" هو نظام لتوثيق البرامج يتعامل معها بنفس الدقة والعمليات المتبعة في كتابة شفرة البرامج. ويشمل ذلك ما يلي:

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