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

بدايةً، توثيق البرمجيات أو توثيق الشيفرة البرمجية المصدرية هي عملية كتابة نصوص ترفق ببرمجيات الكمبيوتر. وهي إما أن تكون نصوصاً توضيحية تشرح كيفية عمل البرمجية أو كيفية استخدامها. وتعرض الأقسام التالية جوانب أخرى من الموضوع.
التوثيق المخصص للمستخدم النهائي
ومن جهة أخرى، 1. البرنامج التعليمي Tutorial: يعتبر البرنامج التعليمي الأسهل والأكثر إفادة للمستعملين الجدد، حيث يتم إرشادهم من خلال الخطوات التي يشرحها لإنجاز مهمة معينة
ومن ناحية أخرى، بخلاف توثيق شيفرة البرمجة، فإن المستندات التي تنتج للمستعملين تكون بسيطة وتصف كيفية استخدام البرنامج. في حالة مكتبة البرمجية، قد تكون وثائق شيفرة البرمجة code ووثائق المستعملين متكافئة ويمكن دمجها، لكن لا ينطبق الأمر على التطبيقات العامة.
هناك 3 طرق استخدامها لتنظيم وثائق المستعمل النهائي:
في هذا الإطار، عادة ما تصف الوثائق التي تنتج للمستعمل النهائي كل خاصية من خصائص البرنامج، وتساعد المستعمل على إدراك ماهية هذه الخصائص. وقد تتضمن هذه الوثائق تعليمات مساعدة لكشف الخلل والمشاكل في البرنامج وطرق التعامل معها. من الأهمية بمكان أن تكون وثائق المستعمل بسيطة وسهلة، ولا تسبب الارتباك للمستعمل، كما يجب أن تكون قابلة للتعديل والتحديث. لا يوجد تنظيم معين يجب أن يتبع عند إعداد وثائق المستعمل النهائي، لكن لا بد أن تحتوي الوثيقة على فهرس. كما يجب أن تتصف هذه الوثائق بالاتساق والبساطة. هذا وقد تعتبر وثائق المستعمل النهائي بمثابة عقد يوضح الأهداف التي بنيت البرمجية لتحقيقها والوظائف التي تؤديها (انظر كذلك: الكتابة التقنية.
وفي هذا السياق، 3.القوائم أو المراجع: في هذه المنهجية، يتم وضع الأوامر أو المهام في قوائم وتجمّع أبجدياً أو منطقياً، ويتم ربطها بالفهارس. تستعمل هذه المنهجية عادة للمستعملين ذوي المستوى المتقدم الذين يعرفون نوع وطبيعة المعلومات التي يبحثون عنها في التوثيق.
وفي السياق ذاته، 2. المنهجية الموضوعية Thematic: حيث تركز فصول وأقسام الوثيقة على موضوع محدد فقط، ويستعمل هذا النوع للمستعملين ذوي المستوى المتوسط. يفضل بعض المؤلفين نقل أفكارهم من خلال المقالات القائمة على المعرفة لتيسير تحقيق احتياجات المستعمل. استعملت هذه المنهجية عادة من قبل المجالات المعرفية الديناميكية كتكنولوجيا المعلومات، حيث يُعنى المستعملون بصورة أكبر باكتشاف أخطاء ومشكلات البرامج والتعامل معها
المفاتيح الأساسية
وفي هذا الصدد، من الأهمية بمكان شمول كافة المعلومات التي يمكن للجميع استخدامها. كما أنه من الضروري تحديث الوثائق عند إجراء أي تغيير على قاعدة البيانات.
الخصائص والقيود
مخطط العلاقات، بما في ذلك المعلومات التالية:
الجداول، الخصائص ومزاياها
التوثيق التقني
وفي هذا الصدد، غالباً ما يحتاج المبرمجون إلى القدرة على إنشاء المعلومات التي لن تكون جزءاً من الشيفرة المركزية، أي كتابة تعليقات وهوامش معينة، والوصول إليها. تكون هذه المعلومات جزءاً من الأنشطة البرمجية العديدة كتتبّع الشيفرة البرمجية وترقيتها. وهي بذا تساعد المبرمج في أي مرحلة من مراحل إنشاء البرامج على التتبع والصيانة. يستعمل Kelp لتخزين التعليقات في ملفات منفصلة وربط المعلومات بالشيفرة المصدرية ديناميكياً.
علاوةً على ذلك، التوثيق التقني هو ما يقصده مبرمج عندما يستعملون التعبير توثيق البرمجيات. عندما يتم إنشاء برمجية فإن Code لا تكفي وحدها. يجب أن تتوفر كذلك بعض النصوص التي تصف الجوانب المختلفة للعمليات المطلوب من البرمجية تنفيذها. من الأهمية بمكان أن تكون وثائق الشيفرة البرمجية شاملة، لكن يجب في الوقت ذاته أن لا تكون طويلة بحيث يصعب تعديلها وحفظها. تستعمل برامج API Writer لكتابة الكثير من الوثائق الخاصة بالبرمجيات كتعليمات الاستخدام. قد تستعمل الوثائق التقنية من قبل المبرمجين أو فاحصي البرامج والمستعمل النهائي للبرمجية. في الوقت الراهن، نرى الكثير من التطبيقات المتقدمة المستعملة في شتى المجالات كالطاقة والنقل والشبكات والفضاء والأمن والحماية والأتمتة الصناعية ومجالات أخرى عديدة. أصبح التوثيق التقني هاماً في هذه المجالات، نظراً لتغيير المعلومات الأساسية والمتقدمة بسرعة خلال فترات زمنية قليلة بما في ذلك التغيرات التي تجرى على معمارية البرامج. لذا، اكتسب التوثيق التقني أهمية عظيمة مؤخراً خصوصاً في عالم البرمجيات.
وفي السياق ذاته، إن فكرة إنشاء التوثيق أوتوماتيكياً جاذبة للمبرمجين لعدة أسباب. مثلًا، نظراً لكون هذه الوثائق مستخلصة من الشيفرة المصدرية نفسها (مثلاً باستخدام الملاحظات والتعليقات) يمكن أن يكتبها المبرمجون عند مراجعة الشيفرة البرمجية، كما يمكنهم استخدام نفس الأدوات المستعملة لإنشاء الشيفرة البرمجية للوثائق. وهذا يسهّل عملية تحديث الوثائق. إحدى سلبيات هذه الأداة هي أن المبرمجين يستطيعون تعديد هذا النوع من الوثائق، وتقع على عاتقهم مسؤولية تحديثها للحصول على المخرجات. هذا ويعتقد البعض أن هذه ميزة إيجابية بدلاً من كونها سلبية.
من جانب آخر، غالباً ما تستعمل أدوات إنشاء الوثائق (كـ دي أكسجين، NDoc، javadoc، EiffelStudio) لإنشاء ملفات الشيفرة البرمجية أوتوماتيكياً، أي أنها تستخلص الملاحظات وتبنى التصميم بالعقود من الشيفرة المصدرية وتُنشئ كتيبات مرجعية ذات صيغ ملفات نصية أو ملفات لغة ترميز النص الفائق. غالباً ما تنظّم ملفات الشيفرة البرمجية بأسلوب «الدليل المرجعي»، ما يتيح للمبرمج سرعة البحث عن class أو وظيفة معينة في البرمجية.
توثيق المعمارية\ التصميم
كذلك، من أهم أجزاء وثيقة التصميم في عملية تطوير البرمجيات ما يعرف بوثيقة تصميم قاعدة البيانات. وتتضمن عناصر التصميم المفاهيمي والمنطقي والفيزيائي. تتضمن هذه الوثيقة معلومات أساسية يحتاج إليها الأشخاص الذين يتعاملون مع قاعدة البيانات. إن الهدف من تحضير وثيقة تصميم قاعدة البيانات هو إنشاء مصدر مشترك لجميع المشاركين، وهم:
ومن جهة أخرى، من أصناف مستندات التصميم تلك المستعملة لأغراض المقارنة أو الدراسات. وغالباً ما تكون بهيئة ورقة بيضاء. وتركز على جانب محدد من النظام وتقترح طرقاً بديلة. فقد ينصب تركيزها على واجهة التطبيق أو شيفرة البرمجة أو التصميم أو حتى على مستوى المعمارية. تلخص هذه المستندات بديلاً أو أكثر وتعدد إيجابيات وسلبيات كل منها. يجب أن توضح كذلك تكلفة كل حل من الحلول المقترحة. تهدف الدراسات غالباً إلى ابتكار الحلول واستنباطها بدلاً من فرض وجهة نظر محددة. ويقبل في هذه الدراسات عدم الخروج باستنتاجات أو أن يكون الاستنتاج أن ليس ثمة بديل من البدائل أفضل من الأساس لتبرير إجراء تغيير. ينبغي التعامل مع هذه الدراسات على أنها مبتغى علمي وليس وسيلة تسويق.
- مصمم قاعدة البيانات
- مبرمج قاعدة البيانات
- مدير قاعدة البيانات
- مصمم البرنامج
وعلى صعيد آخر، توثيق المعمارية هو تصنيف آخر لملف التصميم. تشتق ملفات المعمارية بطريقة ما من ملفات تصميم الكود. تتضمن وثائق المعمارية القليل عن الشيفرة البرمجية نفسها، ولا تصف كيفية برمجة أجزاء معينة من الكود أو حتى سبب وجودها، بل تصف المتطلبات العامة التي تحفّز وجود تلك الأجزاء من الكود. وثيقة المعمارية الجيدة تكون ذات تفاصيل قليلة لكنها تصف المتطلبات بكثافة. وقد تقترح منهجية للتصميم الأولي، لكنها لا تتضمن تفاصيل كثيرة عنه.
العروض
- القيود، كـالمفاتيح الأساسية primary keys والمفاتيح الثانوية foreign keys
- أصول القيود المرجعية
- السياسة المتتالية للقيود المرجعية
مبرمج البرنامج
- عند الحديث عن نظم قواعد البيانات المترابطة، يجب أن يتضمن التوثيق ما يلي:
- مخطط كيان-علاقة (محسن وتتضمن المعلومات التالية وتعريفات واضحة لكل منها):
- مجموعة الكائن وخصائصها
- العلاقات وخصائصها
- المفاتيح المرشحة لكل مجموعة كائن
وثيقة التصميم
- ملفات "إقرأني"
- لغة النمذجة الموحدة UML
- البرمجة المتعلمة Literate programming
دور التوثيق في تطوير البرمجيات
وعلى صعيد آخر، التوثيق التقني: توثيق شيفرة البرمجية Code وخوارزمية والبينيات وواجهة برمجة التطبيقات API.
إضافةً إلى ذلك، المعمارية (الهيكلية)\التصميم - عرض عام للبرمجية. يتضمن وصف العلاقات بالبيئة ومبادئ البناء التي ستستعمل في تصميم عناصر البرمجية.
من جهة ثانية، التسويق: توثيق يشرح كيفية تسويق المنتج البرمجي ويحلل متطلبات السوق.
من جهة ثانية، المتطلبات - توثّق بعبارات تعرّف الخصائص والإمكانيات والميزات ومعايير النظام. وهي الأساس الذي سيتم بناءً عليها تنفيذ البرنامج.
وفي السياق ذاته، التوثيق: عملية ومرحلة هامة من عمليات هندسة البرمجيات. وتتضمن أنواع التوثيق ما يلي:
من جانب آخر، دليل المستعمل: كتيّبات مخصصة لمستعملي البرمجية ومدراء النظام وإختصاصيي الدعم الفني.
توثيق المتطلبات
في هذا الإطار، ترتبط الحاجة لتوثيق المتطلبات بدرجة تعقد وصعوبة المنتج وتأثيره ومتوسط العمر المتوقع للبرمجية. فإذا كانت البرمجية معقدة جداً أو يتم برمجتها من قبل الكثير من الأشخاص (كبرمجيات الهواتف المحمولة) فإن المتطلبات تساعد في هذه الحالة على توضيح ما الذي يجب إنجازه. أما إذا كانت البرمجية حرجة من حيث تأثيرها السلامة وقد يكون لها تأثير سلبي على حياة الإنسان (مثلاً نظم التحكم بالطاقة النووية أو المعدات الطبية) فإن توثيق المتطلبات يصبح أكثر أهمية ويكون في هذه الحالة إلزامياً. إذا كان متوقعاً أن لا يزيد عمر تشغيل البرمجية عن شهر أو شهرين (مثلاً يُستعمل تطبيق للهواتف المحمولة خلال حملة دعائية لفترة محدودة) فإن توثيق المتطلبات لا يكون مهماً. إذا كانت البرمجية إصداراً أولياً بحيث يبنى عليها لاحقاً فإن التوثيق يساعد كثيراً في إدارة التغيير المطلوب تنفيذه لتطوير البرمجية.
كذلك، إن تنوع وتعقد عملية توثيق المتطلبات تجعل منه تحدياً. فقد تكون المتطلبات ضمنية بحيث يصعب توضيحها. لذا يصعب الجزم بالكمية والماهية والوسيلة اللازمة للتوثيق؛ كما يصعب تحديد ما يجب أن يترك لمرحلتي توثيق التصميم والمعمارية. هذا إلى جانب صعوبة معرفة كيف يتعامل الأشخاص المختلفون مع المتطلبات وكيف يقرأونها. لذا، غالباً ما يبقى توثيق المتطلبات غير مكتمل (أو قد لا يتم إنشاؤه أصلاً). بدون التوثيق الملائم للمتطلبات، يصبح التحكم بالتغيير المطلوب إجراؤه على المتطلبات أمراً أكثر صعوبة وأكثر عرضة للخطأ، ما يقلل من جودة البرمجية وزمن تجهيزها للاستخدام (فتصبح كلفتها عالية).
كذلك، غالباً ما يتم تحديد المتطلبات في ملفات متطلبات (مثلاً ملفات معالجات النصوص كـ Word أو معالجات الجداول كـ Excel. وهذه الملفات تساعد في التحكم في درجة الصعوبة المتزايدة أو تغيير طبيعة توثيق المتطلبات.
من جهة ثانية، توثيق المتطلبات هو عبارة عن وصف ما الذي تؤديه أو ستؤديه برمجية معينة. ويستعمل التوثيق طوال مرحلة بناء البرمجية وذلك لتوضيح ما الذي ستؤديه البرمجية. كما يستعمل التوثيق كأساس للاتفاق على الوظائف المرجو تحقيقها من هذه البرمجية. توضع المتطلبات وتستعمل من قبل جميع المشاركين في إنتاج البرمجية بما فيهم: المستعمل النهائي والمستهلك ومدراء الإنتاج والمبيعات ومعماري البرمجيات ومهندسو الاستخدامية والمبرمجون وفاحصو البرمجيات وغيرهم. وبذا فإن توثيق المتطلبات يستعمل لتحقيق أهداف عديدة. تأتي المتطلبات بأنماط متنوعة رمزية وشكلية. وقد تكون المتطلبات على هيئة «أهداف» (مثلاً، بيئة العمل الموزعة) أو «تصميم» (مثلاً، يجب أن يتم البناء بالنقر على ملف التهيئة بواسطة زر الفأرة الأيمن ومن ثم اختيار «بناء») أو أي شيء آخر بينهما. وقد تكتب هذه الأهداف بعبارات بلغة طبيعية أو بالرسم أو بمعادلات رياضية أو بخليط من طرق التعبير هذه.
توثيق البرمجيات المؤتمت - توثيق التطبيقات
من جهة ثانية، لجنة توثيق معايير الأيزو - منظمة دولية تعنى بلجنة المقاييس التي تضع وثائق المقاييس لوثائق المستعملين.
التوثيق المخصص للتسويق
- إثارة حماسة المستعملين المحتملين عن المنتج وترسيخ رغبتهم في استخدامه.
- إعلام المستعملين المحتملين عن كيفية أداء المنتج بما يتوافق مع توقعاتهم
- توضيح مكانة المنتج مقارنة بالبدائل الأخرى.
- ملاحظات
- طالع كذلك
- كاتب API
- مقارنة بين برامج التوثيق
- التصميم بالعقود
- التوثيق
- مساعدة المستعمل
من جانب آخر، من الأهمية بمكان توفير مواد ترويجية للعديد من التطبيقات وذلك لتشجيع المراقبين على قضاء المزيد من الوقت في تعلّم المنتج. وهذا النوع من التوثيق يخدم ثلاث أغراض هي:
وفي السياق ذاته، إن إحدى تقنيات التسويق الجيدة هي توفير «مصطلحات» واضحة وبارزة تجسد النقاط التي ترغب بتوصيلها والتأكيد على قابلية التشغيل البيني للبرنامج مع المنتجات الأخرى التي يوفرها المصنّع.
📝 هل في هذه المقالة خطأ؟
إذا وجدت معلومة تحتاج تصحيحاً أو إضافة، أو أردت حذف المقالة، أرسل لنا طلباً وسنراجعه.
ما رأيك في هذه المقالة؟