Markdown: مشروع Markdown العملي — كتابة README

لا شيء يتفوق على كتابة مستند حقيقي — اليوم سننشئ README كاملاً لمشروع مفتوح المصدر من الصفر.

1. ما ستتعلمه

• تطبيق جمي�� صيغ Markdown بشكل شامل
• كتابة README احترافي لمشروع GitHub
• تنظيم توثيق المشاريع مفتوحة المصدر
• كتابة توثيق API وإرشادات المساهمة
• أفضل ممارسات توثيق المشاريع

2. قصة حقيقية لمؤسس مشروع مفتوح المصدر

(1) نقطة الألم: README فوضوي يخنق نمو المشروع

أصدر كيسي أداة CLI مفتوحة المصدر بجودة تعليمات برمجية رائعة، لكن README كان يحتوي فقط على ثلاث فقرات وأمر تثبيت واحد. بعد شهر من الإصدار، كان لدى المشروع 50 نجمة فقط، وكانت المشكلات تغمر بـ "كيف أستخدم هذا؟"، "ماذا يفعل؟"، و "كيف أساهم؟"

(2) الحل: إعادة كتابة README باستخدام Markdown

درس كيسي ملفات README لـ 10 مشاريع عالية النجوم وأعاد كتابة README المشروع باستخدام Markdown: أضاف شارات المشروع وقائمة ميزات ولقطات شاشة توضيحية وخطوات تثبيت وتوثيق API ودليل مساهمة وترخيصًا. بعد إعادة الكتابة، قفزت النجوم من 50 إلى 800، وانخفضت الأسئلة الأساسية بنسبة 70%.

3. الهيكل القياسي لـ README

يتضمن README الاحترافي على GitHub عادةً هذه الأقسام:

4. مشروع عملي: كتابة README كامل

فيما يلي هيكل README الكامل لمشروع مفتوح المصدر خيالي QuickLog (مكتبة تسجيل خفيفة لـ Python).

(1) اسم المشروع والشارات

استخدم H1 للعنوان وصيغة الصورة التي تشير إلى shields.io للشارات:

العنوان: QuickLog
سطر الشارات: إصدار Python · حالة البناء · الترخيص
الشعار: مكتبة تسجيل خفيفة بدون تكوين لـ Python

الشارات تتيح للزوار رؤية إصدار المشروع وحالة البناء والترخيص بنظرة واحدة.

(2) الميزات

قسم الميزات:
- بدون تكوين: يعمل مباشرة، لا حاجة للتكوين
- تسجيل منظم: يدعم إخراج بتنسيق JSON
- إخراج ملون: ترميز لوني حسب مستوى السجل
- خفيف: Python خالص، بدون تبعيات خارجية

(3) التثبيت والبدء السريع

# التثبيت
pip install quicklog

# البدء السريع
from quicklog import get_logger
logger = get_logger("my_app")
logger.info("بدأ التطبيق")

(4) توثيق API

get_logger(name, level=INFO, format="console")

المعاملات:
| الاسم   | النوع | مستوى السجل الأدنى    |
| المستوى | int  | الحد الأدنى لمستوى السجل |
| التنسيق | str  | "console" أو "json"  |

(5) دليل المساهمة

خطوات المساهمة:
1. تفرع المستودع
2. أنشئ فرع ميزة
3. أودع تعليماتك البرمجية
4. ادفع إلى المستودع البعيد
5. افتح طلب سحب

قائمة التحقق قبل الإيداع:
- التعليمات البرمجية تتبع PEP 8
- الاختبارات تنجح
- التوثيق محدث

ملخص الصيغة: هذا README يطبق تقريبًا كل صيغة من هذا الدرس — العناوين وتنسيق النص والروابط والصور (الشارات) والتعليمات البرمجية (مضمنة ومسورة) والجداول والقوائم (مرتبة/غير مرتبة/مهام) والاقتباسات والفواصل الأفقية والرموز التعبيرية. كل قسم يستخدم الصيغة الأنسب لغرضه.

▶ مثال: تشريح هيكل README كامل

هيكل README القياسي:

العنوان + الشارات (اسم المشروع وحالته)
وصف المشروع (جملة أو جملتان عن الغرض)
الميزات (قائمة نقطية بالإبرازات)
دليل التثبيت (كتلة تعليمات برمجية بأوامر التثبيت)
أمثلة الاستخدام (كتلة تعليمات برمجية بالاس��خدام الأساسي)
مرجع API (جدول بأوصاف المعاملات)
دليل المساهمة (قائمة مرتبة بالخطوات)
الترخيص (معلومات ترخيص مفتوح المصدر)

5. تنظيم توثيق المشروع

يحتاج المشر��ع الناضج مفتوح المصدر عادةً إلى ملفات توثيق إضافية:

جذر-المشروع/
  README.md              # الصفحة الرئيسية للمشروع
  CONTRIBUTING.md        # دليل المساهمة
  CHANGELOG.md           # سجل تغييرات الإصدارات
  LICENSE                # الترخيص
  CODE_OF_CONDUCT.md     # مدونة السلوك
  docs/                  # توثيق مفصل
    installation.md
    getting-started.md
    api-reference.md
    troubleshooting.md

(1) مثال CHANGELOG.md

سجل التغييرات يتضمن رقم الإصدار والتاريخ وفئات التغيير:

الإصدار 2.0.0:
  مضاف: دعم إخراج بتنسيق JSON�� توافق غير متزامن
  تم الإصلاح: إخراج ملون على Windows، إصلاح تسرب الذاكرة

(2) مثال CONTRIBUTING.md

مستند المساهمة يتضمن:
1. إعداد بيئة التطوير
2. أوامر تشغيل الاختبارات
3. دليل أسلوب التعليمات البرمجية
4. متطلبات تقديم طلب السحب

(3) ▶ مثال: من README إلى موقع توثيق كامل

خارطة طريق التوثيق:
1. ابدأ بـ README.md الذي يغطي المعلومات الأساسية
2. أضف CONTRIBUTING.md و CHANGELOG.md حسب الحاجة
3. ابنِ دليل docs/ مع نضوج المشروع
4. انشر موقع توثيق باستخدام MkDocs أو Hugo

▶ مثال: تدقيق مستنداتك تلقائيًا

# التحقق من تنسيق صيغة Markdown
markdownlint README.md

# التحقق من الأخطاء الإملائية
codespell README.md

# التحقق من الروابط المعطلة
lychee README.md

6. قائمة التحقق من جو��ة التوثيق

راجع كل عنصر بعد كتابة مستنداتك:

7. ملخص الدورة

تهانينا على إكمال جميع دروس Markdown الـ 14! إليك نظرة عامة على المعرفة:

من اليوم فصاعدًا، يمكنك كتابة التوثيق التقني و README المشاريع ومنشورات المدونات وملاحظات الدراسة بـ Markdown — هذه المهارة سترافقك طوال مسيرتك التقنية بأك��لها.

❓ أسئلة شائعة

📖 ملخص

• README الجيد يتضمن: العنوان / الشارات، الوصف، الميزات، لقطات الشاشة، التثبيت، الاستخدام، API، المساهمة، الترخيص
• دمج صيغ Markdown المتعددة يجعل التوثيق احترافيًا وقابلاً للقراءة
• المشاريع مفتوحة المصدر تحتاج أيضًا إلى CHANGELOG.md و CONTRIBUTING.md ومستندات داعمة أخرى
• جودة التوثي�� تتطلب فحوصات منتظمة: صلاحية الروابط، قابلية تشغيل التعليمات البرمجية، حداثة لقطات الشاشة
• مستندات Markdown يجب أن تكون تحت التحكم في الإصدار Git
• هذه الدروس الـ 14 تغطي Markdown من الأساسيات إلى التطبيق الواقعي

📝 تمارين

1. مبتدئ: اختر مشروعًا مفتوح المصد�� تعرفه (أو مشروعك الخاص) واكتب README من الصفر بـ Markdown. تضمن على الأقل: وصف المشروع، قائمة الميزات، أوامر التثبيت، وأمثلة الاستخدام.

2. متوسط: أضف CONTRIBUTING.md و CHANGELOG.md إلى مشروعك. يجب أن يغطي CHANGELOG إدخالين إصدارين على الأقل.

3. متقدم: أنشئ موقع توثيق مشروع كامل (استخدم GitHub Pages + Jekyll، أو Hugo) وانشر مستندات Markdown الخاصة بك على الإنترنت. يجب أن يحتوي الموقع على 3 صفحات على الأقل: README/الصفحة الرئيسية، البداية السريعة، ومرجع API.

فريق Web-Tutorial التقني

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

من نحن