أفضل الممارسات

بعد إتقان قواعد Markdown، كيف تكتب وثائق تقنية عالية الجودة سهلة الصيانة؟ هذا الدليل يجمع ممارسات من الأساسيات إلى التقنيات المتقدمة.

تصميم هيكل الوثائق

تنظيم الدلائل

project/
├── README.md                 # نظرة عامة على المشروع
├── docs/
│   ├── index.md             # الصفحة الرئيسية للوثائق
│   ├── getting-started/
│   │   ├── installation.md  # دليل التثبيت
│   │   ├── quick-start.md   # البدء السريع
│   │   └── examples.md      # أمثلة الشيفرة
│   ├── api/
│   │   ├── overview.md      # نظرة عامة على API
│   │   ├── authentication.md # شرح المصادقة
│   │   └── endpoints/       # وثائق الواجهات
│   ├── guides/
│   │   ├── best-practices.md # أفضل الممارسات
│   │   └── troubleshooting.md # استكشاف الأخطاء
│   └── changelog.md         # سجل التحديثات
└── assets/
    └── images/              # موارد الصور

تسلسل مستويات المحتوى

# العنوان الرئيسي - موضوع الوثيقة

مقدمة موجزة عن محتوى وأهداف هذه الوثيقة.

## العنوان الثانوي - الفصول الرئيسية

### العنوان من المستوى الثالث - موضوع محدد

محتوى وتفاصيل وشرح...

#### العنوان من المستوى الرابع - تقسيم المحتوى

تفاصيل التنفيذ المحددة...

##### العنوان من المستوى الخامس - ملاحظات إضافية

ملاحظات ونصائح...

> تنبيه: تجنب أكثر من خمسة مستويات للعناوين لتفادي تعقيد البنية.

معايير كتابة المحتوى

أسلوب اللغة

✅ أسلوب مُوصى به:

1. **استخدم لغة واضحة ومباشرة**
   - تجنب الجمل الطويلة
   - استخدم الصيغة النشطة
   - قلل استخدام المصطلحات التقنية

2. **حافظ على نبرة متسقة**
   - نبرة رسمية لكن ودية
   - طريقة تعبير موجهة للمستخدم
   - تجنب الصياغة التقنية المفرطة

3. **قدم إرشادات محددة**
   - استخدم أرقاماً وأمثلة محددة
   - قدم خطوات عمل واضحة
   - اشمل النتائج المتوقعة

❌ تجنب ما يلي:

- استخدام التعبيرات الغامضة
- الإفراط في استخدام الصيغة المبني للمجهول
- نقص المعلومات السياقية الضرورية
- افتراض أن القارئ لديه معرفة محددة

الفقرات والتنسيق

<!-- ✅ بنية فقرات جيدة -->
## تثبيت Node.js

للبدء في استخدام أدواتنا، تحتاج أولاً إلى تثبيت Node.js. Node.js هو بيئة تشغيل JavaScript تسمح لك بتشغيل كود JavaScript على جانب الخادم.

### متطلبات النظام

قبل التثبيت، تأكد من أن نظامك يستوفي المتطلبات التالية:

- نظام التشغيل: Windows 10+ أو macOS 10.12+ أو Linux
- الذاكرة: 4GB RAM على الأقل
- مساحة التخزين: 1GB مساحة متاحة على الأقل

### خطوات التثبيت

1. قم بزيارة [الموقع الرسمي لـ Node.js](https://nodejs.org/)
2. قم بتنزيل حزمة التثبيت المناسبة لنظام التشغيل الخاص بك
3. قم بتشغيل برنامج التثبيت واتبع التعليمات لإكمال التثبيت
4. افتح terminal للتحقق من التثبيت:

إذا ظهر رقم الإصدار فالتثبيت ناجح.

تثبيت nodejs تحتاج للذهاب إلى الموقع الرسمي ثم التنزيل ثم التثبيت ثم التحقق من رقم الإصدار للتأكد من نجاح التثبيت

## معايير أمثلة الشيفرة

### أفضل ممارسات كتل الشيفرة

إنشاء حساب مستخدم

يوضح المثال التالي كيفية استخدام API لإنشاء مستخدم جديد:

// استيراد المكتبات اللازمة
const axios = require('axios');

// تكوين نقطة نهاية API
const API_BASE_URL = 'https://api.example.com';
const API_KEY = 'your-api-key';

// دالة إنشاء المستخدم
async function createUser(userData) {
  try {
    const response = await axios.post(`${API_BASE_URL}/users`, userData, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('تم إنشاء المستخدم بنجاح:', response.data);
    return response.data;
  } catch (error) {
    console.error('فشل إنشاء المستخدم:', error.response.data);
    throw error;
  }
}

// مثال الاستخدام
const newUser = {
  name: 'أحمد محمد',
  email: 'ahmed@example.com',
  role: 'user'
};

createUser(newUser);

المخرجات المتوقعة:

{
  "id": "12345",
  "name": "أحمد محمد",
  "email": "ahmed@example.com",
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z"
}

ملاحظات مهمة:

• استبدل your-api-key بمفتاح API الفعلي الخاص بك
• تأكد من أن الاتصال بالشبكة يعمل بشكل طبيعي
• يجب الاحتفاظ بمفتاح API بشكل آمن ولا تقم بتقديمه إلى نظام التحكم في الإصدارات

// إنشاء مستخدم
axios.post('/users', data)

هذا المثال ينشئ مستخدماً.

### أمثلة سطر الأوامر

نشر المشروع

1. بناء المشروع

# تثبيت التبعيات
npm install

# تشغيل الاختبارات
npm test

# بناء نسخة الإنتاج
npm run build

2. النشر إلى الخادم

# الاتصال بالخادم
ssh user@server.example.com

# الانتقال إلى مجلد المشروع
cd /var/www/myproject

# سحب أحدث الكود
git pull origin main

# إعادة تشغيل الخدمة
sudo systemctl restart myproject

3. التحقق من النشر

# فحص حالة الخدمة
sudo systemctl status myproject

# عرض السجلات
sudo journalctl -u myproject -f

النتيجة المتوقعة:

• حالة الخدمة تظهر كـ active (running)
• الوصول إلى https://yoursite.com يعرض أحدث إصدار

## إدارة الروابط والاستشهادات

### روابط داخلية

للحصول على تعليمات التثبيت التفصيلية، راجع دليل التثبيت.

بخصوص مصادقة API، راجع وثائق المصادقة.

إذا واجهت مشاكل، راجع دليل استكشاف الأخطاء.

انقر هنا لعرض طريقة التثبيت. التفاصيل في: ./index.md

### روابط خارجية

تم تصميم API الخاص بنا بناءً على أسلوب REST المعماري، ويتابع معيار رموز حالة HTTP.

لمزيد من المعلومات حول JWT، راجع وثائق JWT الرسمية و مواصفة RFC 7519.

• مستودع GitHub 🔗
• عرض مباشر 🌐
• الوثائق الرسمية 📚

### روابط مرجعية (Reference)

ندعم طرق مصادقة متعددة auth-methods، بما في ذلك مفاتيح API و OAuth 2.0 و JWT.

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

## تحسين الصور والوسائط

### معايير استخدام الصور

نظرة عامة على واجهة المستخدم

يوضح الشكل أدناه التخطيط الرئيسي لواجهة التطبيق:

وصف الصورة:

1. شريط التنقل العلوي يحتوي على مداخل الوظائف الرئيسية
2. الشريط الجانبي الأيسر يوفر تنقل سريع
3. منطقة المحتوى الرئيسية تعرض محتوى الصفحة الحالية
4. شريط الحالة السفلي يعرض معلومات النظام

مخطط بنية النظام

شكل: البنية العامة للنظام - يوضح علاقات المكونات

انظر إلى الصورة:

### تنظيم الصور وتسميتها

assets/ ├── images/ │ ├── ui/ │ │ ├── dashboard-overview.png │ │ ├── user-profile-edit.png │ │ └── settings-general.png │ ├── diagrams/ │ │ ├── system-architecture.svg │ │ ├── data-flow-diagram.png │ │ └── user-workflow.png │ └── screenshots/ │ ├── installation-step-1.png │ ├── installation-step-2.png │ └── installation-complete.png

assets/ ├── images/ │ ├── img1.png │ ├── pic2.jpg │ ├── screenshot.png │ └── diagram.svg

## مبادئ تصميم الجداول

### جداول البيانات

قائمة نقاط نهاية API

الطريقة	نقطة النهاية	الوصف	المصادقة	المعاملات
GET	/api/users	الحصول على قائمة المستخدمين	✅	page, limit, sort
POST	/api/users	إنشاء مستخدم جديد	✅	name, email, role
GET	/api/users/{id}	الحصول على مستخدم محدد	✅	id (معامل المسار)
PUT	/api/users/{id}	تحديث معلومات المستخدم	✅	id, name, email
DELETE	/api/users/{id}	حذف المستخدم	✅	id (معامل المسار)

توضيح:

• ✅ يعني أن المصادقة مطلوبة
• جميع نقاط النهاية تحتاج إلى مفتاح API صالح في رأس الطلب
• معاملات المسار يتم تحديدها مباشرة في URL
• معاملات الاستعلام يتم تمريرها بتنسيق ?key=value&key2=value2

مقارنة خطط التسعير

الميزة	النسخة المجانية	النسخة الاحترافية	النسخة المؤسسية
عدد المستخدمين	حتى 5 مستخدمين	حتى 50 مستخدم	غير محدود
مساحة التخزين	1GB	100GB	1TB
استدعاءات API	1,000/شهر	10,000/شهر	غير محدود
الدعم التقني	دعم المجتمع	دعم البريد الإلكتروني	دعم مخصص 24/7
السعر	مجاني	$99/شهر	$999/شهر

ترقية الآن | اتصل بالمبيعات

### عرض بيانات معقدة

متطلبات تكوين الخادم

مواصفات الخادم	التكوين الموصى به
	النشر الصغير (<1K مستخدم)	النشر المتوسط (1K-10K مستخدم)	النشر الكبير (>10K مستخدم)
المعالج	2 أنوية	4 أنوية	8+ أنوية
الذاكرة	4GB	8GB	16GB+
التخزين	50GB SSD	200GB SSD	500GB+ SSD
الشبكة	100Mbps	1Gbps	10Gbps

```

التحكم بالإصدارات والتعاون

إدارة نسخ الوثائق

<!-- ✅ أضف معلومات النسخة في مقدمة المستند -->
---
title: دليل استخدام API
version: 2.1.0
last_updated: 2024-01-15
author: فريق الوثائق التقنية
---

# دليل استخدام API

> ملاحظة النسخة: هذا المستند ينطبق على API v2.1.0 فأعلى.
> للإصدارات الأقدم راجع وثائق الأرشيف.

## سجل التحديثات

### v2.1.0 (2024-01-15)
- إضافة ميزة إدارة مجموعات المستخدمين
- تحسين عملية المصادقة
- إصلاح المشاكل المعروفة

### v2.0.0 (2024-01-01)
- إعادة هيكلة بنية API
- تحديث آلية المصادقة
- إضافة واجهات العمليات المجمعة

معيار رسائل Git

<!-- ✅ صيغة مُنظمة لرسائل الالتزام -->
docs: تحديث وثائق مصادقة API

- إضافة مثال مصادقة OAuth 2.0
- إصلاح الأخطاء في أمثلة الكود
- تحديث الروابط ذات الصلة

closes #123

<!-- ✅ أنواع الالتزامات -->
بادئات النوع:
- docs: تحديث الوثائق
- feat: وثائق ميزة جديدة
- fix: إصلاح أخطاء الوثائق
- style: تعديل التنسيق
- refactor: إعادة هيكلة بنية الوثائق
- test: إضافة اختبارات للأمثلة
- chore: تحديث عملية البناء أو الأدوات المساعدة

معايير التعاون على الوثائق

<!-- إرشادات المساهمة -->
## دليل المساهمة

### عملية الإرسال

1. **Fork المشروع** - إنشاء نسخة شخصية من المشروع
2. **إنشاء فرع** - إنشاء فرع ميزة لتغييراتك
   ```bash
   git checkout -b docs/update-api-guide

3. كتابة المحتوى - اكتب وفقاً لمعايير الوثائق
4. اختبار محلي - تأكد من عرض الوثائق بشكل صحيح
5. إرسال التغييرات - استخدم رسالة إرسال موحدة
6. إنشاء PR - وصف تغييراتك بالتفصيل

نقاط مراجعة المحتوى

• [ ] دقة المحتوى
• [ ] وضوح التعبير اللغوي
• [ ] امتثال التنسيق للمعايير
• [ ] صلاحية الروابط
• [ ] قابلية تشغيل أمثلة الكود
• [ ] عرض الصور بشكل صحيح

## الوصولية والدولنة (i18n)

### تصميم مراعي للوصولية

<!-- ✅ تصميم وثائق يراعي الوصولية -->
### الألوان والتباين

عند استخدام الألوان لتمثيل المعلومات، قدم أيضاً طرق تعريف أخرى:

::: tip نجاح
✅ نجاح: اكتملت العملية
:::

::: danger خطأ
❌ خطأ: فشلت العملية
:::

### النص البديل

قدم نصاً بديلاً ذا معنى لجميع الصور:

![مخطط بنية النظام: يُظهر تدفق البيانات بين العميل وبوابة API والخدمات الصغيرة وقاعدة البيانات](/assets/images/main-interface.png)

### تنقل لوحة المفاتيح

تأكد من أن بنية الوثيقة تدعم التنقل بلوحة المفاتيح:

- استخدام مستويات عناوين معقولة
- توفير روابط الفهرس
- جعل الروابط المهمة سهلة الاكتشاف

### اعتبارات الدولنة

project/ ├── docs/ │ ├── en/ # الوثائق الإنجليزية │ │ ├── README.md │ │ └── api/ │ ├── zh/ # الوثائق الصينية │ │ ├── README.md │ │ └── api/ │ └── ja/ # الوثائق اليابانية │ ├── README.md │ └── api/

إصدارات اللغة

• English
• 中文
• 日本語

آخر تحديث: 15 يناير 2024 (ar) Last updated: January 15, 2024 (en-US) 最終更新日：2024年1月15日 (ja-JP)

## تحسين الأداء

### تحسين تحميل الوثائق

<!-- ✅ تصميم تقسيم الصفحات -->
### تقسيم الوثائق الكبيرة

قسّم الوثائق الطويلة إلى أجزاء:

1. [نظرة عامة](./overview.md) - المفاهيم الأساسية والمقدمة
2. [البدء السريع](./quickstart.md) - دليل البدء في 5 دقائق
3. [البرنامج التعليمي التفصيلي](./tutorial.md) - مسار التعلم الكامل
4. [مرجع API](./api-reference.md) - وثائق API الكاملة
5. [أمثلة الكود](./examples.md) - حالات استخدام عملية

🔍 عرض خيارات التكوين التفصيلية

التكوين المتقدم

# مثال التكوين التفصيلي
server:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem

هذه الخيارات للتحكم الدقيق في بيئة الإنتاج...

تحسين محركات البحث (SEO)

<!-- ✅ تحسين SEO للوثائق -->
---
title: "دليل مصادقة API - حل مصادقة كامل"
description: "تعلم كيفية استخدام OAuth 2.0 و JWT ومفاتيح API للمصادقة الآمنة. يتضمن أمثلة كود وأفضل الممارسات."
keywords: ["مصادقة API", "OAuth", "JWT", "الأمان", "المصادقة"]
---

# دليل مصادقة API

تعلم كيفية التحقق والتفويض بشكل آمن لطلبات API...

## محتوى هذا الفصل

سيغطي هذا الدليل طرق المصادقة التالية:

1. [مصادقة مفتاح API](#مصادقة-مفتاح-api) - طريقة مصادقة بسيطة وسريعة
2. [OAuth 2.0](#oauth-20) - إطار التفويض القياسي في الصناعة
3. [رمز JWT](#رمز-jwt) - مصادقة بدون حالة

ضمان الجودة

قائمة مراجعة المحتوى

<!-- 📋 قائمة فحص جودة الوثائق -->
## فحص ما قبل النشر

### جودة المحتوى
- [ ] المعلومات دقيقة وكاملة
- [ ] التعبير اللغوي واضح
- [ ] الهيكل المنطقي معقول
- [ ] أمثلة الكود قابلة للتشغيل
- [ ] لقطات الشاشة محدثة

### الفحص التقني
- [ ] اختبار صلاحية الروابط
- [ ] تمييز صحيح لبناء الكود
- [ ] عرض الصور بشكل طبيعي
- [ ] تنسيق الجداول صحيح
- [ ] عرض الصيغ الرياضية بشكل طبيعي

### تجربة المستخدم
- [ ] هيكل التنقل واضح
- [ ] وظيفة البحث تعمل بشكل طبيعي
- [ ] التكيف مع عرض الجوال
- [ ] اختبار سرعة التحميل
- [ ] فحص إمكانية الوصول

### قابلية الصيانة
- [ ] تحديث معلومات الإصدار
- [ ] تسجيل سجل التغييرات
- [ ] مزامنة الوثائق ذات الصلة
- [ ] تمييز الميزات المهجورة
- [ ] توفير دليل Migration

جمع ملاحظات المستخدمين

<!-- ✅ آلية جمع الملاحظات -->
## ساعدنا على التحسين

### ملاحظات الوثائق

إذا وجدت أخطاء في الوثائق أو لديك اقتراحات للتحسين:

1. **ملاحظات سريعة**: [إرسال مشكلة](https://github.com/example/docs/issues/new?template=doc-feedback.md)
2. **مناقشة تفصيلية**: [المشاركة في المناقشة](https://github.com/example/docs/discussions)
3. **تحرير مباشر**: [تحرير هذه الصفحة](https://github.com/example/docs/edit/main/docs/api/authentication.md)

### تقييم هذه الصفحة

هل كانت هذه الصفحة مفيدة لك؟

👍 مفيدة | 👎 تحتاج تحسين | 💡 اقتراح

### معلومات الاتصال

- 📧 فريق الوثائق: docs@example.com
- 💬 الدعم التقني: support@example.com
- 🐦 وسائل التواصل الاجتماعي: [@ExampleDocs](https://twitter.com/ExampleDocs)

قواعد ذات صلة

• تضمين HTML - ميزات HTML
• الصيغ الرياضية - تعبيرات LaTeX
• المخططات - رسم المخططات
• الأدوات والإضافات - أدوات التوثيق

أدوات وموارد

أدوات جودة الوثائق

• textlint: تدقيق النص وأسلوبه
• markdownlint: فحص قواعد Markdown
• alex: فحص لغة شمولية
• Hemingway Editor: تحليل قابلية القراءة

منصات التعاون

• GitBook: تعاون على وثائق الفرق
• Notion: إدارة وثائق ومعرفة
• Confluence: تعاون مؤسسي
• Slab: منصة وثائق حديثة

أدوات التحليل

• Google Analytics: تحليل زيارات الوثائق
• Hotjar: تحليل سلوك المستخدم
• Mixpanel: تتبع التفاعل
• FullStory: جلسات المستخدم كاملة

أدوات الأتمتة

• GitHub Actions: بناء ونشر الوثائق
• Zapier: أتمتة سير العمل
• IFTTT: قواعد أتمتة بسيطة
• n8n: أتمتة مفتوحة المصدر

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