قواعد تحرير التوثيق

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

الفصل اللغوي

• لغة واحدة في كل ملف.
• الصفحات الإنجليزية تستخدم نثرًا إنجليزيًا فقط.
• الصفحات العربية تستخدم نثرًا عربيًا فقط.
• تبقى أسماء API المشتركة داخل backticks فقط، مثل URootUi وUTextLabel.

شكل الصفحة

يُفضَّل اتباع بنية قصيرة ومتكررة:

1. لماذا توجد هذه الصفحة.
2. الحد الأدنى من النموذج الذهني المطلوب.
3. القواعد العملية أو الأمثلة.
4. الأمثلة المرتبطة.
5. أنواع API المرتبطة عند الحاجة.

قواعد التسمية

• استخدم الاسم العام الرسمي كما يظهر في Rust.
• لا تبتكر أسماء بديلة للأنواع العامة.
• عند ذكر مثال، اذكر اسمه واسم الـ package المالكة له معًا.

قواعد ربط الأمثلة

عند الإشارة إلى مثال من داخل صفحة شرح:

• اربط دائمًا إلى المدخل المرجعي داخل docs/src/ar/examples/index.md
• اذكر الـ package المالكة
• لا تستخدم أمرًا من الشكل cargo run -p <package> --example <name> إلا إذا كان مصدر المثال موجودًا فعلًا في هذا الفرع؛ وإلا فاربط إلى فهرس التوفر أو إلى الحزمة الحية الحالية

قواعد API Docs

• يجب أن يشرح rustdoc النية والمعنى، لا أن يعيد أسماء الحقول فقط.
• تُفضَّل أمثلة no_run القصيرة على الفقرات الطويلة.
• المساعدات الداخلية التي لا تدخل في القصة العامة للمكتبة يجب إخفاؤها أو تقليل بروزها.

قواعد التناظر بين اللغتين

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