توثيق البرمجيات - ويكيبيديا

توثيق البرمجيات (بالإنجليزية: Software Documentation)‏ أو توثيق الشيفرة البرمجية المصدرية هي عملية كتابة نصوص ترفق ببرمجيات الكمبيوتر. وهي إما أن تكون نصوصاً توضيحية تشرح كيفية عمل البرمجية أو كيفية استخدامها.

التوثيق: عملية ومرحلة هامة من عمليات هندسة البرمجيات. وتتضمن أنواع التوثيق ما يلي:

1. المتطلبات - توثّق بعبارات تعرّف الخصائص والإمكانيات والميزات ومعايير النظام. وهي الأساس الذي سيتم بناءً عليها تنفيذ البرنامج.
2. المعمارية (الهيكلية)\التصميم - عرض عام للبرمجية. يتضمن وصف العلاقات بالبيئة ومبادئ البناء التي ستستخدم في تصميم عناصر البرمجية.
3. التوثيق التقني: توثيق شيفرة البرمجية Code وخوارزمية والبينيات وواجهة برمجة التطبيقات API.
4. دليل المستخدم: كتيّبات مخصصة لمستخدمي البرمجية ومدراء النظام وإختصاصيي الدعم الفني.
5. التسويق: توثيق يشرح كيفية تسويق المنتج البرمجي ويحلل متطلبات السوق.

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

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

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

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

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

• مصمم قاعدة البيانات
• مبرمج قاعدة البيانات
• مدير قاعدة البيانات
• مصمم البرنامج
• مبرمج البرنامج

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

• مخطط كيان-علاقة (محسن وتتضمن المعلومات التالية وتعريفات واضحة لكل منها):
  • مجموعة الكائن وخصائصها
  • العلاقات وخصائصها
  • المفاتيح المرشحة لكل مجموعة كائن
  • الخصائص والقيود
• مخطط العلاقات، بما في ذلك المعلومات التالية:
  • الجداول، الخصائص ومزاياها
  • العروض
  • القيود، كـالمفاتيح الأساسية primary keys والمفاتيح الثانوية foreign keys
  • أصول القيود المرجعية
  • السياسة المتتالية للقيود المرجعية
  • المفاتيح الأساسية

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

التوثيق التقني هو ما يقصده مبرمج عندما يستخدمون التعبير توثيق البرمجيات. عندما يتم إنشاء برمجية فإن Code لا تكفي وحدها. يجب أن تتوفر أيضاً بعض النصوص التي تصف الجوانب المختلفة للعمليات المطلوب من البرمجية تنفيذها. من الأهمية بمكان أن تكون وثائق الشيفرة البرمجية شاملة، لكن يجب في الوقت ذاته أن لا تكون طويلة بحيث يصعب تعديلها وحفظها. تستخدم برامج API Writer لكتابة العديد من الوثائق الخاصة بالبرمجيات كتعليمات الاستخدام. قد تستخدم الوثائق التقنية من قبل المبرمجين أو فاحصي البرامج والمستخدم النهائي للبرمجية. في الوقت الراهن، نرى العديد من التطبيقات المتقدمة المستخدمة في شتى المجالات كالطاقة والنقل والشبكات والفضاء والأمن والحماية والأتمتة الصناعية ومجالات أخرى عديدة. أصبح التوثيق التقني هاماً في هذه المجالات، نظراً لتغيير المعلومات الأساسية والمتقدمة بسرعة خلال فترات زمنية قليلة بما في ذلك التغيرات التي تجرى على معمارية البرامج. لذا، اكتسب التوثيق التقني أهمية عظيمة مؤخراً خصوصاً في عالم البرمجيات. غالباً ما تستخدم أدوات إنشاء الوثائق (كـ دي أكسجين، NDoc، javadoc، EiffelStudio) لإنشاء ملفات الشيفرة البرمجية أوتوماتيكياً، أي أنها تستخلص الملاحظات وتبنى التصميم بالعقود من الشيفرة المصدرية وتُنشئ كتيبات مرجعية ذات صيغ ملفات نصية أو ملفات لغة ترميز النص الفائق. غالباً ما تنظّم ملفات الشيفرة البرمجية بأسلوب «الدليل المرجعي»، ما يتيح للمبرمج سرعة البحث عن class أو وظيفة معينة في البرمجية.

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

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

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

هناك 3 طرق استخدامها لتنظيم وثائق المستخدم النهائي:

1. البرنامج التعليمي Tutorial: يعتبر البرنامج التعليمي الأسهل والأكثر إفادة للمستخدمين الجدد، حيث يتم إرشادهم من خلال الخطوات التي يشرحها لإنجاز مهمة معينة^[1]

2. المنهجية الموضوعية Thematic: حيث تركز فصول وأقسام الوثيقة على موضوع محدد فقط، ويستخدم هذا النوع للمستخدمين ذوي المستوى المتوسط. يفضل بعض المؤلفين نقل أفكارهم من خلال المقالات القائمة على المعرفة لتيسير تحقيق احتياجات المستخدم. استخدمت هذه المنهجية عادة من قبل المجالات المعرفية الديناميكية كتكنولوجيا المعلومات، حيث يُعنى المستخدمون بصورة أكبر باكتشاف أخطاء ومشكلات البرامج والتعامل معها^[2]

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

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

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

إن إحدى تقنيات التسويق الجيدة هي توفير «مصطلحات» واضحة وبارزة تجسد النقاط التي ترغب بتوصيلها والتأكيد على قابلية التشغيل البيني للبرنامج مع المنتجات الأخرى التي يوفرها المصنّع.

• كاتب API
• مقارنة بين برامج التوثيق
• التصميم بالعقود
• Docstring
• التوثيق
• مساعدة المستخدم
• وثيقة التصميم
• ملفات "إقرأني"
• لغة النمذجة الموحدة UML
• البرمجة المتعلمة Literate programming

• kelp - . Kelp - إطار عمل للشيفرة البرمجية الرئيسية للتوثيق الهيكلي والتصميمي والتقني
• توثيق البرمجيات المؤتمت - توثيق التطبيقات
• لجنة توثيق معايير الأيزو - منظمة دولية تعنى بلجنة المقاييس التي تضع وثائق المقاييس لوثائق المستخدمين.

قالب:هندسة البرمجيات