6 أفضل أمثلة لتوثيق البرامج وأفضل الممارسات

هل تريد معرفة النجاح وراء منتجات البرمجيات الجيدة والمزدهرة؟

إنها وثائقهم.

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

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

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

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

لذلك ، دعنا نبدأ!

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

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

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

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

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

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

بعض المستندات المنتجة في دورة حياة تطوير البرمجيات ، المصدر - cds.cern.ch

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

1. وثائق المشروع

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

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

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

2. المتطلبات وتوثيق التصميم

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

ويشمل المكونات الرئيسية مثل:

• نظرة عامة على النظام
• أهداف وأهداف عالية المستوى
• المتطلبات الوظيفية
• معايير القبول
• بنية النظام
• كومة التكنولوجيا

بينما تركز وثائق المتطلبات على ما يجب أن يفعله النظام ، تركز وثائق التصميم على كيفية بناء النظام.

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

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

3. الوثائق الفنية

تغطي الوثائق الفنية كيفية بناء أنظمة البرمجيات وتشغيلها وصيانتها.

في وثائق البرمجيات ، يجب عليك إنشاء وثائق فنية لشرح:

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

لدينا دليل كامل لإنشاء وكتابة الوثائق الفنية ، والتحقق من ذلك!

4. وثائق المستخدم

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

ويشمل:

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

تختلف وثائق المستخدم قليلاً عن الوثائق الفنية ، لدينا بعض الأدلة التي ستساعدك على معرفة المزيد عنها:

• 5 أفضل أمثلة وثائق مستخدم (Good & Bad + Tips)
• كيفية إنشاء دليل المستخدم: من الصفر إلى البطل (دليل كامل)

5. اختبار الوثائق

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

ويشمل:

• خطة الاختبار وحالات الاختبار
• قوائم المراجعة التي يجب متابعتها أثناء اختبار ميزة البرامج
• إرشادات جودة الرمز
• الاختبارات الآلية

6. الوثائق الصيانة / الأمن

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

ويشمل:

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

7. الوثائق القانونية والامتثال

الوثائق القانونية والامتثال لضمان تتبع البرمجيات معايير قانونية وتنظيمية وصناعية.

الوثائق القانونية مثل:

• اتفاقية ترخيص المستخدم النهائي (EULA)
• شروط الخدمة (TOS)
• سياسة الخصوصية
• تراخيص البرمجيات ومعلومات الاستخدام

وثائق الامتثال مثل:

• حماية البيانات والامتثال للخصوصية ، والتي تتضمن لوائح مثل الناتج المحلي الإجمالي أو CCPA أو HIPAA.
• الامتثال الأمني
• امتثال إمكانية الوصول
• اللوائح الخاصة بالصناعة

استكشاف : ما هي وثائق البرمجيات؟

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

1. وورد

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

يتم استخدام WordPress على 43 ٪ من جميع مواقع الويب على الويب. لذلك يجب أن تكون وثائقها واحدة من الأفضل لخدمة ملايين الأشخاص من جميع أنحاء العالم.

ويشمل ذلك المطورين أو المصممين أو المدونين أو الكتاب أو أي شخص يريد إنشاء موقع ويب.

تنقسم الوثائق الرئيسية WordPress إلى ثلاثة أقسام مختلفة :

1. تعلم WordPress: يتضمن أدلة في شكل دورات متعمقة ومقاطع فيديو ودروس تعليمية مكتوبة. يستهدف المبتدئين والمستخدمين المتوسطين والمتقدمين.
2. الوثائق الرئيسية: تهدف إلى المستخدمين العاديين. لتقديم نظرة عامة على ميزات WordPress ، في شكل دروس مكتوبة قصيرة مباشرة.
3. موارد المطورين: تهدف إلى المطورين الذين يقومون بإنشاء سمات WordPress أو الإضافات أو ترغب في تمديد WordPress مع الترميز المخصص. ويشمل بدء أدلة ، وثائق API ، وأمثلة الترميز.

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

أشياء يجب تعلمها من وثائق برنامج WordPress:

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

ما لا يعجبك في وثائق WordPress:

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

2. قاعدة المعرفة Herothemes

وثائق البرمجيات الخاصة بنا.

إنه ليس أفضل مثال ، ولكن بالنظر إلى أن معظمكم لديه موقف مشابه لنا:

• لا فكرة من أين تبدأ
• ميزانية منخفضة

يمكن أن يكون مثالا جيدا للتعلم منها.

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

أشياء يجب تعلمها من مثال وثائق Herothemes:

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

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

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

ما لا يعجبك في وثائق Herothemes:

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

لدينا بعض الأدلة لمساعدتك في إنشاء موقع توثيق مع WordPress:

• كيفية إنشاء قاعدة معرفة WordPress (دليل خطوة بخطوة)
• كيفية إنشاء وثائق داخلية

3. وثائق محفظة برامج Barn2

تبيع BARN2 منتجات برامج متعددة استنادًا إلى WordPress و WooCommerce المستخدمة في أكثر من 90،000 موقع على شبكة الإنترنت.

قد يكون تقديم وثائق برامج متعددة من بوابة واحدة أمرًا صعبًا ، لكن Barn2 يفعل ذلك بشكل جميل.

يجب عليك بالتأكيد النظر في مثال Barn2 إذا كان لديك منتجات متعددة.

أشياء يجب تعلمها من مثال وثائق Barn2:

BARN2 صاغوا بعناية فائقة صفحة الدعم الخاصة بهم. والتي يمكن رؤيتها مع وظائفها الشاملة وفائدتها.

عند زيارة صفحة الدعم الخاصة بهم ، ستجد شريط بحث بارز مع خيار لتحديد منتج معين .

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

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

الحديث عن وثائق البرنامج الرئيسية:

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

ما لا يعجبك في وثائق Barn2:

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

يستخدم BARN2 أيضًا قاعدة المعرفة البطولية لإنشاء وثائق البرمجيات الخاصة بهم.

4. دليل مستخدم iPhone

هناك العديد من الأشياء التي يعجبها واعجاب في وثائق مستخدم iPhone (أدلة برامج iOS).

إنه وثائق برمجية رائعة مع تعليمات سهلة المتابعة ، شيء من هذا القبيل يمكنك توقعه من Apple.

أشياء يجب تعلمها من مثال وثائق iPhone:

وثيقة iPhone تبدو مذهلة .

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

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

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

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

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

بخلاف تجميل وثائقها ، لم تنس Apple استخدام SEO بشكل صحيح . أن تكون محددًا:

• هيكل العنوان والوانين
• الترابط في شكل من أشكال TOC ، والمشاركات ذات الصلة ، والتنقل السابق والقادم

نظام التغذية المرتدة دليل رائع . يمكنك النقر فوق نعم أو لا ، وإذا لزم الأمر ، قدم ملاحظات أيضًا.

لا يبدو نظام التعليقات رائعًا ، ولكن عندما يكون لديك ملايين المستخدمين الذين يعطونك ملاحظات ، فإن نعم بسيط أو لا تتبع مفيد حقًا للتحقق من أداء الأدلة (لا يمكنك قراءة كل هذه التعليقات ، هل يمكنك ذلك؟) .

توفر Apple أيضًا أدلة تستند إلى إصدارات البرامج (في هذه الحالة ، إصدار iOS).

ما لا يعجبك في وثائق iPhone:

لقد أثنت كثيرًا على وثائق iPhone أعلاه ، ولكن هناك أيضًا بعض الأشياء المزعجة.

وخاصة جزء الملاحة.

• جدول المحتويات ليس مفيدًا ، حيث يتضمن جميع روابط التوجيه.
• أيقونة البحث صغيرة جدًا بحيث لا يمكن ملاحظتها.

5. وثيقة تصميم البرمجيات (مثال داخلي)

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

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

• ما هي الاحتياجات من البرنامج
• نِطَاق
• كيف ستعمل
• مراجع

سيساعد وجود معلومات مفصلة في تجنب العديد من الاجتماعات المستقبلية ، وتدريب الموظفين الجدد ، وإنشاء إرشادات ملموسة.

يمكنك تعلم الكثير من وثيقة تصميم برامج Advisor Trip Trip.

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

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

الأشياء التي يجب تعلمها من هذا المثال:

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

6. وثائق Google

من لا يعرف جوجل؟ نحن نستخدم برامجهم الأولى كل يوم ، مثل Chrome أو Gmail أو Google Maps أو Google Drive أو YouTube.

وهي متوفرة لكل من أجهزة الكمبيوتر والأجهزة المحمولة. نظام التشغيل والأجهزة والقرارات والإعدادات المختلفة.

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

أشياء يجب تعلمها من وثائق برامج Google:

• استخدام كبير لعلامات التبويب والأكورديون لتبسيط مجموعات المحتوى.

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

• نظام ردود فعل رهيبة. على غرار بعض الأمثلة المذكورة أعلاه ، يتضمن Google أيضًا نظام ردود فعل نعم/لا يجمع أيضًا ملاحظات من المستخدمين.

لكن Google يذهب خطوة واحدة إلى الأمام هنا. لديهم نظام معمول به يجمع التعليقات بناءً على أقسام محددة . وهو بديهية للغاية وسهل.

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

ما لا يعجبك في وثائق Google:

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

الأفكار النهائية

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

فيما يلي بعض الكلمات الأخيرة:

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

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

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

جربها!