كتابة التوثيق التقني

مقدمة

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

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

ماذا ستتعلم في هذه المقالة؟

الفصل	المحتوى	المفهوم الأساسي
الفصل 1	أنواع وهيكل التوثيق	كيفية كتابة أنواع مختلفة من الوثائق
الفصل 2	مبادئ الكتابة	واضح، دقيق، موجز
الفصل 3	مقارنة عملية	توثيق جيد مقابل توثيق سيء
الفصل 4	صيانة التوثيق	إبقاء التوثيق محدثًا

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

---

0. نظرة عامة: لماذا يُعد التوثيق التقني مهمًا؟

الكود يخبر الحاسوب "كيف"، والتوثيق يخبر البشر "لماذا". المشروع بدون توثيق كجهاز كهربائي بدون دليل استخدام — يعمل، لكن استخدامه يعتمد كليًا على التخمين.

قيمة التوثيق الجيد

• تقليل تكلفة التواصل: الموظفون الجدد يتعلمون بأنفسهم، تقليل الإجابات المتكررة
• حفظ سياق القرارات: تسجيل "لماذا"، وليس فقط "ماذا"
• تعزيز مصداقية المشروع: التوثيق الجيد هو واجهة مشاريع المصدر المفتوح
• تسريع التعاون: توثيق واجهات برمجة التطبيقات يتيح التطوير المتوازي للواجهة الأمامية والخلفية

---

1. أنواع وهيكل التوثيق

من خلال المكون التفاعلي التالي، تعرف على الهيكل القياسي لأنواع مختلفة من التوثيق:

Documentation structure template - click to switch document types

1Project name + one-line description▶

2Quick start▶

3Features▶

4Usage examples▶

5Contributing + license▶

1.1 أنواع التوثيق الشائعة

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

1.2 الهيكل الذهبي لـ README

يجب أن يتضمن README الجيد:

1. اسم المشروع + وصف في جملة واحدة: خلال 3 ثوانٍ تعرف ما هو
2. البدء السريع: أقل خطوات لتشغيله
3. الميزات: نقاط البيع الرئيسية
4. التثبيت: متطلبات البيئة التفصيلية وخطوات التثبيت
5. أمثلة الاستخدام: كود قابل للنسخ واللصق
6. دليل المساهمة: كيفية المشاركة
7. الترخيص: المعلومات القانونية

---

2. مبادئ الكتابة

2.1 الوضوح أولاً

<!-- سيء: غامض -->
هذه الدالة تعالج البيانات.

<!-- جيد: محدد وواضح -->
تحويل بيانات الطلبات الخام إلى تنسيق الفاتورة، بما في ذلك حساب الضرائب وتحويل العملات.

2.2 التوجيه للقارئ

قبل كتابة التوثيق، اسأل: من سيقرأ هذا التوثيق؟ ما المعلومات التي يحتاجها؟

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

2.3 أمثلة الكود هي أفضل توثيق

<!-- سيء: وصف نصي فقط -->
استدعِ دالة createUser، مع تمرير اسم المستخدم والبريد الإلكتروني كمعاملات.

<!-- جيد: قدم مثالًا قابلًا للتنفيذ -->
const user = await createUser({
  name: 'أحمد',
  email: 'ahmed@example.com'
})
// يُرجع: { id: 'u_123', name: 'أحمد', createdAt: '2025-01-15' }

---

3. مقارنة عملية

من خلال المكون التفاعلي التالي، قارن بين الكتابة التقنية الجيدة والسيئة:

Technical writing comparison - click to switch cases

❌ Poor writing

// Process data
function process(d) {
  // ...
}

✅ Better writing

/**
 * Convert raw order data into invoice format.
 * @param {Order} order - Raw order object
 * @returns {Invoice} Formatted invoice
 * @throws {ValidationError} When order data is incomplete
 */
function toInvoice(order) {
  // ...
}

Improvement points:Explain why, not just whatDocument parameter and return typesDescribe exceptional cases

3.1 اتفاقية رسائل الالتزام

<!-- سيء -->
fix bug
update code

<!-- جيد (Conventional Commits) -->
fix: إصلاح شاشة بيضاء في صفحة تسجيل الدخول على Safari
feat: دعم التصدير المجمّع للتقارير بصيغة PDF
docs: تحديث كود المثال في قسم مصادقة API

3.2 فن التعليقات

// سيء: يصف "ماذا" (الكود يقوله بالفعل)
// المرور عبر المصفوفة
for (const item of items) { ... }

// جيد: يشرح "لماذا"
// المرور بالترتيب العكسي، لأن الحذف بالترتيب الطبيعي يتخطى العنصر التالي
for (let i = items.length - 1; i >= 0; i--) { ... }

---

4. صيانة التوثيق

4.1 التوثيق كالكود

أدِر التوثيق والكود في نفس المستودع، بنفس سير العمل:

• تغييرات التوثيق تُرسل مع الكود في طلب سحب واحد
• CI يتحقق من تنسيق التوثيق وصلاحية الروابط
• يُحدّث التوثيق بشكل متزامن مع كل إصدار

4.2 تجنب تعفّن التوثيق

المشكلة	الحل
توثيق قديم	إلزام تحديث التوثيق مع تغييرات الكود (فحص في طلب السحب)
بدون صيانة	تعيين مسؤول عن التوثيق
محتوى مكرر	مصدر معلومات واحد، والبقية تُربط بروابط

---

5. دعم الذكاء الاصطناعي: تحسين جودة التوثيق بالنماذج اللغوية

النماذج اللغوية "موهوبة بطبيعتها" في مجال الكتابة التقنية — توليد التوثيق، تحسين التعبير، وترجمة المحتوى كلها نقاط قوتها.

5.1 توليد توثيق API

Prompt:

من كود مسارات Express التالي، أنشئ توثيق API كامل يتضمن:
- مسار نقطة النهاية وطريقة HTTP
- معاملات الطلب (معاملات المسار، معاملات الاستعلام، نص الطلب) وأنواعها
- أمثلة على الاستجابات الناجحة والخاطئة
- مثال على الاستدعاء باستخدام curl

[الصق كود المسارات الخاص بك]

5.2 تحسين الكتابة التقنية

Prompt:

حسّن تعبير التوثيق التقني التالي وفقًا للمتطلبات التالية:
1. لغة موجزة وواضحة، إزالة التعبيرات الزائدة
2. استخدام صيغة المبني للمعلوم بدلا من المبني للمجهول
3. الحفاظ على دقة المصطلحات التقنية
4. إضافة أمثلة كود عند الحاجة
حافظ على المعنى الأصلي، فقط حسّن جودة التعبير.

[الصق محتوى التوثيق الخاص بك]

5.3 توليد README

Prompt:

من معلومات المشروع التالية، أنشئ README.md عالي الجودة:
- اسم المشروع: [الاسم]
- وصف في جملة واحدة: [الوصف]
- الحزمة التقنية: [اذكرها]
- الميزات الأساسية: [اذكرها]

يجب أن يتضمن: مقدمة المشروع، البدء السريع، الميزات،
خطوات التثبيت (مع كود)، أمثلة الاستخدام، دليل المساهمة، الترخيص.

نصائح استخدام الذكاء الاصطناعي

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

---

6. الخلاصة

1. النوع المناسب: أنواع مختلفة من التوثيق لها هياكل وأساليب كتابة مختلفة
2. الوضوح أولاً: محدد، دقيق، وموجّه للقارئ
3. الأمثلة كمحرك: مثال كود جيد يساوي ألف كلمة
4. الصيانة المستمرة: التوثيق كالكود، يتطور مع المشروع

تأمل أخير

كتابة التوثيق ليست إهدارًا للوقت، بل توفير للوقت في المستقبل. الثلاثون دقيقة التي تقضيها اليوم قد توفر لـ 10 أشخاص ساعة كل منهم. التوثيق الجيد هو أفضل استثمار للفريق.

---

قراءات إضافية

• دليل الكتابة: دورة Technical Writing المجانية من جوجل عملية ومفيدة.
• أدوات التوثيق: VitePress، Docusaurus، GitBook وأطر توثيق حديثة أخرى.
• توثيق API: مواصفة OpenAPI/Swagger هي معيار الصناعة لتوثيق واجهات برمجة التطبيقات.
• نصيحة عملية: ابدأ بكتابة README جيد لمشروعك الخاص.