الإرشاد والتوثيق التقني
طوّر أعضاء الفريق المبتدئين من خلال البرمجة الثنائية والملاحظات المقدّمة في الوقت المناسب، واكتب ADRs للقرارات المعمارية، وحافظ على توثيق حي يثق به الآخرون
الإرشاد والتوثيق التقني درس مجاني في Frontend Academy على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Frontend Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Frontend Academy 4 دروس في المجموع.
المهندس الخبير يضاعف أثر الآخرين
في المستوى الخبير، لا تتمثل مهمتك في كتابة أكبر قدر من الكود، بل في جعل فريقك أفضل. ساعد المبتدئين على التطور، واكتب توثيقًا يوسّع نطاق معرفتك، وأجرِ مراجعات كود تعليمية، وشكّل البنية المعمارية بحيث يتمكن الآخرون من التحرك بسرعة وأمان.
الإرشاد من خلال البرمجة الثنائية
تُعد البرمجة الثنائية أسرع طريقة لتطوير المبرمج المبتدئ. اجلسا معًا (أو استخدما مشاركة الشاشة)، ودَع المبتدئ يقود بينما توجّهه. قاوم تولي المهمة — اشرح طريقة تفكيرك، واطرح أسئلة على الطريقة السقراطية.
تحديات بالحجم المناسب
امنح المبتدئين مهامًا تتجاوز قدراتهم الحالية بقليل. السهولة الزائدة = لا نمو. الصعوبة الزائدة = غرق وإحباط. اضبط المستوى: «أعتقد أنك تستطيع إنجاز هذا مع قليل من المساعدة — ويسعدني أن نعمل عليه معًا إذا واجهت مشكلة».
مراجعة الكود بوصفها تعليمًا
في PR الخاصة بالمبتدئين، اشرح السبب وراء كل تعليق غير بسيط. أضف روابط إلى التوثيق ذي الصلة، أو PR سابقة، أو مقالات. المراجعة السيئة: «استخدم useCallback». المراجعة الجيدة: «تُعاد هذه الدالة في كل عملية render — وتمريرها إلى عنصر ابن يستخدم memo'd يسبب عمليات إعادة render غير ضرورية. تقوم useCallback بحفظها مؤقتًا. إليك PR مثالًا استخدمنا فيه ذلك: #1234».
سجلات القرارات المعمارية (ADRs)
يوثّق ADR خيارًا معماريًا مهمًا: ما الذي قررناه، ولماذا، والبدائل التي درسناها، والمقايضات التي قبلناها. سيشكرك مستقبلك على ما توثقه لنفسك اليوم.
# ADR-0007: Use TanStack Query for server state
Date: 2026-05-01
Status: Accepted
## Context
We currently scatter useEffect+fetch+useState patterns across the app.
Cache invalidation is inconsistent, race conditions cause stale data.
## Decision
Adopt TanStack Query (@tanstack/react-query v5) for all server state.
## Consequences
+ Built-in caching, deduplication, optimistic updates.
+ Standard pattern across team.
- Adds ~13KB gzipped.
- Team needs to learn query keys conventions.
## Alternatives Considered
- SWR: smaller, but fewer features (no mutations).
- Apollo Client: overkill (we don't use GraphQL).
- Custom hook: doesn't solve cache invalidation.
## References
- React Query docs: ...أين توجد ADRs
خزّن ADRs في docs/adr/ داخل المستودع، ورقّمها بالتسلسل. فهي توجد بجانب الكود الذي تصفه. ومن الأدوات: adr-tools وlog4brains لإنشاء واجهة ويب قابلة للتصفح.
جودة README
يحتاج كل package ومكتبة وميزة رئيسية إلى README. أدرج فيه: ما الذي يفعله، وكيفية تثبيته، وكيفية استخدامه (مع أمثلة كود)، وكيفية المساهمة، وكيفية تشغيل الاختبارات، وكيفية تصحيح الأخطاء. التطوير الموجّه بـ README: اكتب README أولًا، ثم ابنِ المنتج وفقًا للمواصفات الواردة فيه.
تعليقات الكود المضمّنة — متى تستخدمها
ينبغي أن تشرح التعليقات لماذا، لا ماذا. فالكود يوضح ماذا يحدث. أما التعليقات فتشرح: قواعد العمل، والمقايضات غير الواضحة، والروابط إلى التذاكر أو الأخطاء، والتحذيرات من المشكلات الخفية.
// BAD: comment restates the code
// Increment counter by 1
counter++;
// GOOD: comment explains business context
// Stripe webhook can arrive twice — increment only if signature is fresh.
// See: https://stripe.com/docs/webhooks/best-practices#idempotency
if (!seen.has(event.id)) counter++;Runbooks للمهام التشغيلية
وثّق كيفية تنفيذ المهام التشغيلية المتكررة أو الخطرة: «كيفية تدوير مفتاح Stripe API»، و«كيفية التعافي من عملية نشر فاشلة»، و«كيفية تصحيح استجابة API بطيئة». سيتمكن أعضاء الفريق الجدد من اتباعها من دون طلب مساعدتك.
التوثيق المتجدد
التوثيق القديم أسوأ من عدم وجود توثيق. أضف إليه تاريخًا. وراجعه كل ثلاثة أشهر. واحذف التوثيق الذي لا يحدّثه أحد. والأفضل: أنشئ التوثيق من الكود (Storybook للعناصر، وTypeDoc لواجهات API، وOpenAPI لنقاط النهاية).
المحاضرات التقنية وجلسات Brown-Bag
قدّم لفريقك محاضرات مدتها 20 إلى 30 دقيقة عمّا تعلمته: مكتبة جديدة، أو قصة عن تصحيح أخطاء، أو نمطًا وجدته مفيدًا. فهذا يجبرك على تنظيم أفكارك، ويعلّم الآخرين.
بناء الأمان النفسي
المبتدئون الذين يخافون من طرح الأسئلة لا يتطورون. اجعل عبارة «لا أعرف» أمرًا طبيعيًا. وفّر بيئة آمنة لارتكاب الأخطاء — واحتفِ بالتحليل اللاحق للحادثة، لا بإلقاء اللوم. وبصفتك مهندسًا خبيرًا، تحدد ردود أفعالك نبرة الفريق.
فخ البرمجة البطولية
لا تكن الشخص الذي يعالج كل حادثة في بيئة الإنتاج بمفرده. وثّق الإصلاح، واعمل مع زميل في المرة التالية، وأتمت تشخيص المشكلة. الفريق الذي يحتاج إلى بطولاتك فريق هش.
تحقق سريع
ما الغرض الأساسي من سجل القرار المعماري (ADR)؟
خلاصة: الإرشاد والتوثيق
المهندس الخبير = مضاعفة أثر الآخرين، لا كتابة أكبر قدر من الكود. اعمل بالبرمجة الثنائية، وعلّم من خلال مراجعة الكود، وامنح تحديات بالحجم المناسب. تلتقط ADRs الموجودة في docs/adr/ أسباب اتخاذ القرارات. أنشئ README لكل package. تشرح التعليقات لماذا، لا ماذا. استخدم Runbooks للمهام التشغيلية. يتفوق التوثيق المتجدد (Storybook وTypeDoc وOpenAPI) على ملفات Markdown الثابتة. ابنِ الأمان النفسي. وتجنب البرمجة البطولية.
الأسئلة الشائعة
هل درس «الإرشاد والتوثيق التقني» مجاني؟
نعم — نص درس «الإرشاد والتوثيق التقني» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Frontend Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Frontend Academy 4 دروس في المجموع.
ماذا ستتعلم في «الإرشاد والتوثيق التقني»؟
طوّر أعضاء الفريق المبتدئين من خلال البرمجة الثنائية والملاحظات المقدّمة في الوقت المناسب، واكتب ADRs للقرارات المعمارية، وحافظ على توثيق حي يثق به الآخرون تتمرن على Frontend Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Frontend Academy؟
لا تُشترط خبرة سابقة. Frontend Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.
كم من الوقت يستغرق درس «الإرشاد والتوثيق التقني»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Frontend Academy هذا؟
نعم. كل درس في Frontend Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- مقابلات تصميم الأنظمة للواجهة الأمامية
- ثقافة مراجعة الشيفرة وأفضل ممارسات PR
- الإرشاد والتوثيق التقني
- مواكبة المستجدات: قراءة المواصفات والمقترحات