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

يمكن العثور على مقدمة لطيفة لوثائق المشروع المعدة جيدًا على أدلة github: https://guides.github.com/features/wikis/. ينص هذا على أن "يجب أن تحتوي README على المعلومات الضرورية فقط للمطورين لبدء استخدام المشروع والمساهمة فيه".

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

مقدمة سريعة

- عنوان المشروع:: هذا أمر لا بد منه لكل README.

- شارات الحالة:: إذا كنت تستخدم أي مقاييس خارجية لجودة التعليمات البرمجية أو الاختبار الآلي أو غيرها من الأدوات، فإن بداية المستند مكان جيد لتبين للآخرين ما إذا كانت تعمل.

- الوصف:: تضمين بضع جمل عن المشروع لوصف الغرض الرئيسي منه وما يقوم به بسرعة.

جدول المحتويات

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

معلومات عامة

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

- نماذج بالحجم الطبيعي:: مكان لروابط لموارد نماذج UI/UX بالحجم الطبيعي إن وجدت.

• معلومات أخرى مثل الوصول إلى الخوادم أو التكامل مع واجهات برمجة التطبيقات الخارجية:: تتضمن الأمثلة عنوان URL لمثيل التدريج، وبيانات اعتماد الوصول غير الحساسة (!) المشتركة، وروابط إلى الوثائق، وبعض الإرشادات، وما إلى ذلك.

التركيب

- المتطلبات:: المتطلبات الأساسية التي يجب الوفاء بها قبل بدء إعداد التطبيق، مثل تثبيت الأدوات الخارجية.

- الإعداد:: تعليمات خطوة بخطوة لاتباعها لبدء المشروع وتشغيله.

- الإعدادات:: وصف مكان تخزين الإعدادات المحلية وتوفير إرشادات حول كيفية تلقي الإعدادات الخاصة بك.

- التكوين المحلي:: إذا كانت هناك بعض الحالات للإعداد المحلي، فهذا مكان جيد للتوضيح.

التطوير

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

النشر

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

أفكار أخرى لأقسام منفصلة

- وثائق واجهة برمجة التطبيقات (API)

- سجل التغييرات

- الموارد الخارجية:: مكان لجميع أنواع الروابط التي قد تكون مفيدة.

- مكدس التطبيقات:: قائمة بمكدس التطبيقات التي نستخدمها في المشروع - قد تحتوي على وصف موجز واسم الموفر.

الفريق

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

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

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

شيء آخر: "التعليمات" هي المفتاح، لذا اكتبها كثيرًا. شكراً لك!

اقرأ المزيد:

• مبدأ الفتح المغلق. هل يجب أن أستخدمه؟
• كيف تكتب كودًا جيدًا وعالي الجودة؟
• Vuelendar. مشروع كودست جديد يستند إلى Vue.js