ما هو توثيق البرامج؟ أنواع وأفضل الممارسات للبدء

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

ولكن ما هو توثيق البرامج حقًا ، وكيف يمكنك البدء في إنشائه لمشروعك؟

في هذا المنشور ، سنبحث في كل ما تحتاج لمعرفته حول توثيق البرامج ، بما في ذلك ما يلي:

• ما هو توثيق البرامج؟
• الأنواع المختلفة لوثائق البرامج (مع أمثلة)
• كيفية نشر وثائق البرامج الخاصة بك (أفضل الأدوات)
• بعض أفضل الممارسات لإنشاء وثائق برامج عالية الجودة

دعونا نحفر!

ما هو توثيق البرامج؟

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

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

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

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

يمكنك تقسيم الأنواع المختلفة من وثائق البرامج تقريبًا إلى عدة فئات عامة.

الاعتبار الأول هو نوع الشخص المقصود بالوثائق:

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

الاعتبار الثاني هو ما إذا كانت الوثائق مخصصة لجمهور خارجي أو داخلي:

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

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

دعنا نقسم هذه الأنواع من وثائق البرامج بمزيد من التفاصيل ...

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

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

للحصول على مثال حقيقي لتوثيق البرامج للمستندات التي تركز على المطورين ، يمكنك الاطلاع على وثائق "المطورين" الخاصة بـ Gravity Forms والتي تغطي موضوعات مختلفة مثل:

• خطافات PHP (لـ WordPress)
• كائنات البيانات
• PHP API
• قاعدة البيانات
• REST API

على سبيل المثال ، إليك ما تبدو عليه وثائق REST API:

أمثلة على توثيق البرامج لوثائق المستخدم

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

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

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

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

كيفية نشر وثائق البرنامج: أفضل ثلاثة أدوات لتوثيق البرامج

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

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

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

قاعدة المعرفة البطولية

قاعدة المعرفة البطولية هي مكون إضافي لقاعدة المعرفة والتوثيق لبرنامج WordPress الشهير مفتوح المصدر.

باستخدام Heroic Knowledge Base ، يمكنك استضافة مستنداتك بنفسك والحفاظ على التحكم الكامل ، مع الاستمرار في الوصول إلى جميع الميزات التي تحتاجها لإنشاء وثائق برامج فعالة.

فيما يلي بعض الميزات الأساسية التي تحصل عليها مع Heroic Knowledge Base:

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

نظرًا لأن Heroic Knowledge Base و WordPress مستضافان ذاتيًا ومفتوحان المصدر ، فأنت أيضًا حر في تعديل الإعداد حسب الحاجة.

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

تبدأ قاعدة المعرفة البطولية من 149 دولارًا فقط في السنة.

اقرأ المستندات

قراءة المستندات هي أداة توثيق تركز على مساعدتك في إنشاء وثائق المطور.

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

يمكنك إدارة المحتوى وسجل المراجعة باستخدام Git ثم نشر مستنداتك على واجهة أمامية.

فيما يلي بعض الميزات البارزة الأخرى في قراءة المستندات:

• تحليلات مدمجة لمعرفة ما يقرأه المستخدمون ويبحثون عنه.
• يدعم العديد من الإصدارات المتزامنة ، والتي يمكن أن تكون مفيدة إذا كنت تقدم إصدارات متعددة من برنامجك - على سبيل المثال مجموعة واحدة من الوثائق للإصدار 1.0 وأخرى للإصدار 2.0.
• تصدير الوثائق بتنسيقات مختلفة بما في ذلك PDF و HTML و epub.
• اقتراحات البحث الحية لمساعدة المستخدمين في العثور على المستندات.

قراءة المستندات مجانية للاستخدام إذا كان لديك مشروع برمجي مفتوح المصدر.

بالنسبة لمنتجات البرمجيات التجارية ، هناك خدمة مدفوعة لقراءة المستندات للأعمال تبدأ من 50 دولارًا في الشهر.

GitBook

GitBook هي أداة توثيق برامج فنية أخرى تتيح لك إدارة وثائقك باستخدام Git ، مع دعم مستودعات GitHub و GitLab.

أو ، إذا كنت لا تريد استخدام Git ، يتيح لك GitBook أيضًا إنشاء وثائقك باستخدام محرر نصوص أو استيرادها من ملفات markdown أو .doc.

فيما يلي بعض الميزات البارزة الأخرى التي يقدمها GitBook:

• التحكم في الإصدار لتتبع المراجعات وسجل الإصدار.
• التحرير المباشر للفريق وهو أمر مفيد إذا كنت بحاجة إلى أن يتعاون مؤلفون متعددون في المقالات.
• نظّم المقالات باستخدام "المسافات" و "المجموعات" - يمكن أن تحتوي كل مساحة على مجموعات متعددة بداخلها.
• خيار تصدير PDF بحيث يمكن للمستخدمين بسهولة تصدير وثائقك كتنزيل PDF.

GitBook مجاني للمشاريع غير الربحية أو مفتوحة المصدر.

بالنسبة لمشاريع البرامج التجارية ، يبدأ GitBook بسعر 8 دولارات لكل مستخدم شهريًا ، بحد أدنى 5 مستخدمين. هذا يعني أن أقل سعر شهري هو 40 دولارًا في الشهر.

أفضل الممارسات لإنشاء وثائق البرامج

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

فكر في أهداف المستخدمين واحتياجاتهم

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

• من هو المستخدم الذي تكتب عنه؟
• ما الذي يحاول المستخدم تحقيقه؟
• ما هو مستوى المعرفة التقنية التي يمتلكها المستخدم؟

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

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

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

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

قم بتضمين وثائق البرامج في عملية التطوير

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

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

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

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

استخدم تنسيقًا ونمطًا متسقين

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

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

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

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

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

استخدم الخبراء لكتابة الوثائق الفنية

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

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

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

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

تسهيل اكتشاف المحتوى على الأشخاص (بحث / تصفية)

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

لمحاولة تجنب هذه المشكلة ، سترغب في التركيز على تحسين إمكانية اكتشاف وثائق البرنامج.

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

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

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

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

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

تتضمن العديد من أدوات التوثيق وظائف البحث المباشر المضمنة ، بما في ذلك قاعدة المعارف البطولية.

حافظ على تحديث وثائق البرنامج

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

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

بخلاف ذلك ، لن تكون وثائقك "غير مفيدة" فحسب ، ولكنها قد تخلق في الواقع ارتباكًا لدى المستخدمين.

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

استخدم ملاحظات العملاء لتحسين وثائقك

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

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

لأتمتة عملية ملاحظات العملاء ، ستحتاج إلى البحث عن أداة إدارة الوثائق التي تتضمن ميزات مضمنة لتعليقات العملاء.

على سبيل المثال ، يتيح المكوِّن الإضافي لقاعدة المعرفة Heroic للمستخدمين تقييم مقالة على أنها مفيدة أو غير مفيدة ، كما يتيح لهم اختياريًا تقديم ملاحظات ذات شكل حر.

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

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

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

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

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

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

لنشر تلك الوثائق ، يمكنك استخدام أداة مفتوحة المصدر مثل Heroic Knowledge Base ، والتي تعتمد على برنامج WordPress القوي.

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

إذا كنت تريد معرفة المزيد ، انقر هنا للذهاب إلى قاعدة المعارف البطولية.