كتابة التوثيق التقني
ملفات README وسجلات القرارات ورسائل الالتزام
7 دقيقة للقراءة
الكتابة التقنية الجيدة توفر على فريقك ساعات. هذه المستندات الثلاثة هي أكثر مهام الكتابة شيوعاً للمطورين.
كتابة README
البنية
# اسم المشروع — وصف من سطر واحد
## Quick Start — كيف تشغّله في 3 خطوات
## Prerequisites — ما يجب تثبيته أولاً
## Installation — تعليمات الإعداد خطوة بخطوة
## Usage — أمثلة كود
## Contributing — كيف تساهم
نصائح كتابة README
| افعل | لا تفعل |
|---|---|
| ابدأ بما يفعله (جملة واحدة) | ابدأ بتاريخ المشروع |
| أظهر مثال كود مبكراً | اكتب فقرات نظرية أولاً |
| اذكر المتطلبات بوضوح | افترض أن الجميع لديهم نفس الإعداد |
كتابة رسائل الالتزام
أنواع Conventional Commits
| النوع | متى تستخدم | مثال |
|---|---|---|
| feat | ميزة جديدة | feat(auth): add OAuth2 login |
| fix | إصلاح خطأ | fix(api): handle null user |
| refactor | إعادة هيكلة | refactor(db): extract query builder |
| docs | توثيق فقط | docs: update API examples |
| chore | صيانة | chore: upgrade React to v19 |
رسائل جيدة مقابل سيئة
✗ "fix bug" → غامض جداً
✓ "fix(checkout): prevent double-charge on retry" → واضح ومحدد
✗ "update code" → لا يقول شيئاً
✓ "refactor(auth): replace JWT library with jose" → يشرح ماذا ولماذا
سجلات القرارات المعمارية (ADRs)
ADR يوثّق لماذا اتُخذ قرار تقني.
عبارات ADR الرئيسية
"We chose X over Y because [specific reason]."
اخترنا X بدل Y لأن [سبب محدد]
"The trade-off is [what we gain] vs [what we lose]."
المفاضلة هي [ما نكسب] مقابل [ما نخسر]
"This decision can be revisited if [condition changes]."
يمكن مراجعة هذا القرار إذا [تغير شرط]
:::