عبدالله بن سنكر: قائمة توثيق مشروعك اللي يفهمها المطوّر الجاي

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

قبل القائمة: التوثيق اللي ما ينقرأ أسوأ من عدمه

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

١. ملف README: أول ساعة للمستلم

هذا أول ملف يفتحه أي مطوّر، وهدفه واحد: يشغّل المشروع على جهازه في أقل من ساعة بدون ما يتصل على أحد. اللي لازم يكون فيه:

• سطران يشرحان وش المشروع ومين يستخدمه.
• المتطلبات بإصداراتها: إصدار Node أو Flutter، ومدير الحزم، وقاعدة البيانات.
• خطوات التشغيل المحلي بالترتيب، أمراً أمراً، كما تنكتب في الطرفية.
• قائمة متغيّرات البيئة في ملف مثل .env.example: الأسماء ووصف كل واحد، بدون القيم الحقيقية.
• كيف تتشغّل الاختبارات، وكيف يُنشر المشروع، ولأي بيئة.
• وين تنكتب المهام والأخطاء المعروفة، عشان المستلم ما يكتشف مشكلة معروفة من جديد.

٢. خريطة المعمار في صفحة وحدة

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

٣. سجل القرارات: ليش، مو بس وش

الكود يقول لك وش انعمل، لكنه ما يقول ليش. وأخطر شي يسويه مطوّر جديد إنه «يصلّح» قراراً كان مقصوداً. الحل اللي تعتمده فرق كثيرة اسمه سجل قرارات المعمار (Architecture Decision Records): ملف قصير لكل قرار مهم، فيه السياق، والقرار، والبدائل اللي انرفضت، والعواقب المتوقعة. مثلاً: «اخترنا قاعدة بيانات علائقية بدل مستندية لأن الفواتير مترابطة مع العملاء والعقود، ونتحمل في المقابل تعقيد الترحيلات». نص صفحة مكتوبة اليوم توفّر نقاشاً كاملاً بعد سنة. ولو تغيّر القرار لاحقاً، لا تحذف الملف القديم: اكتب قراراً جديداً يشير له ويشرح وش تغيّر، فيبقى تاريخ التفكير كاملاً قدّام أي شخص يستلم المشروع بعدك.

٤. الأشياء اللي تضيع أول

هذي البنود نادراً تنكتب، وهي أول ما تنفقد لما يمشي المطوّر:

• الحسابات وملكيتها: مسجّل النطاق، والاستضافة، وإعدادات DNS، وحساب Apple Developer، وحساب Google Play. والأصح إنها باسم صاحب المشروع أو منشأته، والمطوّر يدخل بصلاحية مضافة، مو العكس.
• مكان الأسرار، مو الأسرار نفسها: «مفتاح الدفع محفوظ في إعدادات البيئة في لوحة الاستضافة» سطر مفيد، ونسخ المفتاح في ملف التوثيق خطأ أمني.
• المهام المجدولة: أي شي يشتغل لحاله، مثل تذكيرات يومية أو تقارير أسبوعية أو تنظيف بيانات، ووقته ووين معرّف.
• الروابط الواردة (webhooks): الخدمات الخارجية اللي تنادي على خادمك، وعلى أي عنوان، لأن تغيير النطاق يكسرها بصمت.
• مواعيد التجديد: النطاق، واشتراك المطوّرين السنوي في آبل، وأي خدمة مدفوعة. انتهاء واحد منها بدون ما يدري أحد يوقف المشروع.
• مناطق الحذر: «هذا الجزء يبدو غريباً لكنه يتعامل مع حالة كذا، لا تلمسه بدون اختبار».

وأضف لهذي البنود دليل طوارئ قصيراً: لو طاح الموقع، وش أول ثلاث أشياء تنفحص؟ وين سجلات الخادم؟ كيف ترجع لنسخة سابقة؟ وكيف تسترجع قاعدة البيانات من آخر نسخة احتياطية؟ هذي الصفحة ما يحتاجها أحد أغلب السنة، لكن يوم تحتاجها يكون المطوّر الجديد تحت ضغط، وعملاؤك ينتظرون، وما فيه وقت يكتشف الإجابات من الصفر. ودليل يتقرأ في خمس دقائق يختصر عليه ساعة من التخبط في أسوأ توقيت ممكن.

٥. داخل الكود: التوثيق اللي ما يحتاج ملفاً

التعليق الجيد يشرح السبب، مو اللي يشوفه القارئ بعينه. «نزيد واحد على العداد» تعليق ما يضيف شي، و«نزيد هنا لأن بوابة الدفع تعيد المحاولة مرتين» تعليق ينقذ. والأنواع في TypeScript و Dart توثيق بحد ذاتها: دالة ترجّع نوعاً واضحاً تشرح نفسها. والاختبارات توثيق حي للسلوك المتوقع، والفرق عن الملفات إنها تفشل لو صارت قديمة. ولو المشروع فيه واجهة برمجية يستخدمها تطبيق جوال أو طرف ثالث، فوصفها بمعيار مثل OpenAPI يخلّي أي مطوّر يعرف النقاط والمدخلات بدون ما يقرأ كود الخادم.

وكيف تعرف إن التوثيق كافٍ؟ اختبره. أعطِ المستودع لمطوّر ما شافه قبل، وراقبه يحاول يشغّله بدون مساعدة. كل سؤال يسأله سطر ناقص في التوثيق. عبدالله عبدالرحيم بن سنكر الكندي يتعامل مع هذا الاختبار كجزء من تسليم أي مشروع في منصة أزهل الرقمية، لأن صاحب المشروع لازم يملك مشروعه فعلاً: كوده، وحساباته، والمعرفة اللي تخليه يكمل مع أي مطوّر يختاره بعدين.