تخطي إلى المحتوى الرئيسي

عملية الأدلة

شعار الأدلة

تعرف أكثر على عملية المساهمة في ZAP-Docs على هذه الصفحة. العملية مكتوبة بترتيب زمني عبر هذه الصفحة، لذا ننصحك بالبدء من هنا.

الخطوة 1: اقتراح المحتوى​

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

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

نصيحة

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

ما المواضيع التي نبحث عنها؟​

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

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

قائمة الأدلة المطلوبة​

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


ملاحظة

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

تقديم الاقتراح​

الآن بعد أن تأكدت من أن اقتراحك مناسب لتوثيقنا، توجه إلى مستودع ZAP Docs على GitHub وافتح قضية باستخدام قالب اقتراح مساهمة. يرجى اتباع القالب المقدم والتأكد من ملء كل التفاصيل اللازمة. سيُطلب منك أيضًا تأكيد قبولك لشروط وأحكام برنامج المساهمات، والتي يمكن الاطلاع عليها في شروط المساهمة.

تحذير

تأكد من إدخال معرف ZAP الخاص بك بشكل صحيح لضمان استلام مكافأتك على الحساب الصحيح!

بعد تقديم اقتراحك، نهدف للرد عليك خلال 3-5 أيام. ستتلقى ردًا مباشرًا داخل قضية GitHub الخاصة بك.

نصيحة

تواجه مشاكل؟ لا تتردد في الانضمام إلى سيرفر Discord الخاص بـ ZAP-Hosting حيث سنكون مجتمع ZAP سعداء بمساعدتك والإجابة على أي استفسارات. بدلاً من ذلك، تواصل معنا عبر تذكرة على موقعنا واذكر "برنامج المساهمات - الأدلة" في رسالتك ليتم تحويلها إلى فريق مساهمات ZAP-Hosting.

في ردنا، سنزودك بتعليقات إضافية أو تفاصيل نرغب في تعديلها بخصوص اقتراحك. إذا كان هناك مشكلة، سنتابعها معك مباشرة في قضية GitHub الخاصة بك.

الخطوة 2: كتابة الدليل​

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

ملاحظة

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

المتطلبات الأساسية:

الخطوة الأولى هي إنشاء نسخة fork خاصة بك من مستودع ZAP-Docs على GitHub. يمكنك فعل ذلك بالتوجه إلى مستودع ZAP Docs على GitHub والضغط على زر Fork في أعلى الصفحة.

يجب أن تسمي المستودع بناءً على الاقتراح الذي تم قبوله وتحدد خيار Copy the master branch only. بعد ذلك، اضغط على زر الإنشاء وانتظر بضع ثوانٍ حتى يتم إنشاء النسخة بنجاح.

مع وجود نسخة fork خاصة بك جاهزة، يمكنك الآن الانتقال إلى القسم التالي لإكمال مساهمتك. هناك طريقتان رئيسيتان لإنتاج المحتوى، إما مباشرة عبر موقع GitHub أو استنساخ المستودع محليًا. ميزة الطريقة الأولى أنها أكثر سهولة للمستخدم، بينما ميزة الطريقة المحلية أنك تستطيع اختبار Docusaurus محليًا لمعاينة التغييرات مباشرة.

نصيحة

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

طرق إنشاء الأدلة​

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

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

ملفات التوثيق مسماة باتفاقية بسيطة، حيث تشير الكلمة الأولى إلى نوع الدليل، عادة لعبة، منتج أو قسم، وأي كلمات تالية تشير إلى القسم المحدد. ننصحك بتصفح موقع ZAP-Docs المباشر لتجد القسم المناسب الذي ينتمي إليه الدليل. كمثال، dedicated-windows.md يشير إلى قسم السيرفر المخصص، تحديدًا لنظام تشغيل Windows.

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

في هذا المثال، كان اقتراحنا إنشاء دليل جديد للعبة Rust، تحديدًا عن الأوامر التي توفرها اللعبة. من خلال مراجعة موقع ZAP-Docs و/أو المستودع، نرى أن قسم Rust موجود بالفعل تحت فئة سيرفرات الألعاب. بناءً على اتفاقية التسمية المذكورة سابقًا والأدلة الموجودة، يمكننا استنتاج أن الدليل الجديد يجب أن يُسمى rust-commands.md.

لإنشاء ملف جديد، توجه إلى مستودع GitHub، افتح مجلد docs وعلى الجانب الأيمن من الشاشة، اختر Add File. في القائمة، اضغط على خيار Create new file الذي سيفتح تبويبًا جديدًا.

في أعلى الصفحة ضمن مسار الملف، يمكنك تعيين اسم الملف. كما حددنا سابقًا، سيكون rust-commands.md في مثالنا.

معلومات

تأكد من إضافة امتداد الملف .md لأن كل الأدلة بصيغة Markdown.

الجزء التالي يتضمن إضافة بيانات وصفية رئيسية في بداية الملف. أسهل طريقة لفعل ذلك هي فتح ملف آخر مثل rust-plugins.md ونسخ علامات البيانات الوصفية العلوية. ثم يمكنك تعديل كل قيمة لتتناسب مع دليلك الجديد، والأهم هو حقل id الذي يجب أن يطابق اسم ملفك (بدون .md).

باستخدام مثالنا، يجب أن يحتوي الملف الآن على التالي:

---
id: rust-commands
title: "Rust: أوامر الإدارة"
description: "معلومات عن أوامر الإدارة للعبة Rust من ZAP-Hosting"
sidebar_label: أوامر الإدارة
services:
  - gameserver
---
ملاحظة

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

الاستمرار: إنشاء المحتوى​

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

حافظ على عملك آمنًا

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

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

يمكنك استخدام زر Preview أعلى نافذة التحرير للتبديل إلى وضع المعاينة الذي يعرض معاينة تقريبية، والعودة مرة أخرى عبر زر Edit.

عناصر Docusaurus

يرجى ملاحظة أن بعض عناصر Docusaurus الخاصة مثل التنبيهات (مثل :::note, :::tip وغيرها) أو التبويبات قد لا تظهر بشكل صحيح عند المعاينة عبر GitHub لأنها ليست جزءًا من Markdown التقليدي، لكنها ستظهر بشكل صحيح أثناء الاختبار المحلي والإنتاج.

اتبع إرشاداتنا

يرجى الرجوع إلى الإرشادات لكل ما يتعلق بـ Markdown، الهيكل، المصطلحات والمزيد.

بعد إجراء التغييرات، استخدم زر Commit changes... الذي سيعرض لك نافذة.

أدخل رسالة التزام مفيدة تشرح ما قمت به ووصفًا موسعًا عند الحاجة. أخيرًا، قم بالالتزام بالتغييرات. هذا سيرفعها إلى نسخة fork الخاصة بك. يمكنك الآن التوجه إلى قسم تقديم المحتوى لإنشاء طلب سحب (Pull Request) لتقديم المحتوى إلى مستودع ZAP-Docs الرئيسي.

اختياري: اختبار البناء محليًا​

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

نصيحة

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

ملاحظة

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

المتطلبات الأساسية:

الجزء الأول من العملية هو استنساخ نسخة fork الخاصة بك. أسهل وأبسط طريقة هي عبر GitHub Desktop باختيار Add ثم Clone repository واختيار نسخة fork الخاصة بك.

يمكنك أيضًا استخدام Git لتحقيق ذلك. أنشئ مجلدًا جديدًا، في هذا المثال سنستخدم Docs Test. ادخل المجلد وافتح Git Bash (انقر يمين واختر Git Bash على ويندوز). توجه إلى GitHub وانسخ رابط نسخة fork الخاصة بك. بعد ذلك، نفذ الأمر التالي مع استبدال [your_url] بالرابط:

git clone [your_url]

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

npm install

قد يستغرق هذا بعض الوقت، لكن عند الانتهاء يجب أن ينشئ مجلد node_modules داخل مجلد المستودع. إذا ظهرت أخطاء، فمن المحتمل أنك لم تثبت Node.js.

الخطوة الأخيرة هي تشغيل موقع التوثيق محليًا. استخدم الأمر التالي لبناء موقع الأدلة:

npm start

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

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

الخطوة 3: تقديم المحتوى​

بعد إجراء مساهماتك اللازمة والتي تعتقد أنها تتبع إرشاداتنا بدقة وتتمتع بأعلى جودة، يمكنك إنشاء طلب سحب (Pull Request). يمكنك فعل ذلك بالتوجه إلى نسخة fork الخاصة بك من مستودع ZAP Docs، والضغط على نص Contribute الموجود تحت الأزرار الرئيسية وفتح طلب سحب.

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

بعدها، ضع عنوانًا مناسبًا يشرح ما تم إنجازه. ضمن الوصف، تأكد من ذكر/ربط اقتراحك باستخدام #000 مع رقم معرف الاقتراح. إذا لم تجده في القائمة، يمكنك بسرعة التوجه إلى مستودع ZAP Docs على GitHub، ادخل قسم القضايا وابحث عن اقتراحك مع رقم المعرف.

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

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

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

الخطوة 4: نشر تغييرات الدليل ودفع المكافأة​

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

معلومات

مكافأة هذا النوع من المساهمات تعتمد على عدة عوامل، أبرزها جودة وحجم المحتوى المكتوب، إلى جانب معايير أخرى يقيمها فريق مساهمات ZAP. اقرأ المزيد عن معاييرنا في المكافآت.

مبروك على مساهمتك في أدلة ZAP-Hosting! نحن نقدر كل مساهماتك! 💚

إعدادات الكوكيز