في اجتماع مراجعة منتج، قال مهندس إن الفريق «أضاف ميزة جديدة». سأل أحد الحاضرين: ماذا كانت المشكلة قبلها؟ وما البدائل التي رُفضت؟ وما حدود الحل؟ لم تكن الإجابات جاهزة. لم يكن النقص في العمل، بل في السرد الذي يجعل العمل مفهومًا. الميزة موجودة، لكن قيمتها مختفية لأن أحدًا لم يوثق الرحلة التي أنتجتها. التوثيق الهندسي الجيد ليس أرشيفًا للكود، بل جزء من قيمة المنتج: يقلل ارتباك المستخدم، ويختصر وقت الفريق التالي، ويحوّل التحديث من خبر عابر إلى معرفة قابلة للاستخدام.
من «أضفنا ميزة» إلى «هذا ما تعلمناه»
عبارة «أضفنا ميزة» تصف النتيجة ولا تصف سببها. القارئ لا يعرف هل الميزة تعالج بطئًا، أم تمنع خطأً متكررًا، أم تستبدل حلًا قديمًا لم يعد مناسبًا. عندما تكتب المشكلة أولًا، يصبح التحديث قصة قرار: كان هناك عائق، وجُرّبت حلول، واختير أحدها لسبب محدد. هذه القصة لا تفيد المطور الجديد فقط، بل تساعد المستخدم على معرفة متى يعتمد على الميزة ومتى يبحث عن بديل. القيمة ليست في طول النص، بل في عدد الأسئلة التي يمنعها، وفي القرارات التي يجعلها قابلة للنقاش بدل أن تظل افتراضات صامتة.
ثلاث طبقات من الكتابة لا تختلط
هناك ثلاث طبقات من الكتابة حول أي منتج برمجي. الأولى الدليل المرجعي: كيف تستخدم الميزة، وما مدخلاتها ومخرجاتها. الثانية سجل التغييرات: ما الذي أُضيف أو أُصلح في إصدار معين. الثالثة السرد الهندسي: لماذا اتُخذ القرار، وما الظروف التي جعلته معقولًا. الطبقتان الأولى والثانية ضروريتان، لكن أكثر الفرق تكتفي بهما، فيختفي التفكير الذي أنتج المنتج. السرد الهندسي لا يكرر الدليل، بل يشرح المساحة بين «ما يعمل» و«ما كان يمكن أن يعمل». وهو أيضًا أكثر الطبقات قدرة على إفادة مطور يعمل في منتج مختلف، لأنه ينقل نمط التفكير لا تفاصيل الواجهة.
سيناريو واقعي: جلسة تنقطع في منتصف المهمة
لنفترض — والمثال افتراضي وليس تقريرًا عن قياس فعلي — أن فريقًا يعمل على Social Browser، وهو برنامج لإدارة Profiles وأتمتة سير العمل. يأتي مستخدم يدير عدة Profiles ويشغّل مهمة تمتد بينها، فتنتهي إحدى الجلسات فجأة أو تنقطع الشبكة في منتصف الخطوات. تظهر رسالة خطأ عامة، فيظن المستخدم أن الأتمتة نفسها معطلة، بينما المشكلة في حالة الجلسة أو في اتصال مؤقت.
في التوثيق الجيد، لا يُكتب هنا «حسّنّا معالجة الأخطاء». يُشرح أن الفريق واجه حالتين مختلفتين: انقطاعًا عابرًا يمكن استئنافه، وجلسة لم تعد صالحة تحتاج إلى إعادة تهيئة. ثم تُذكر البدائل: إعادة المحاولة تلقائيًا دون تمييز، أو تحديث الجلسة بصمت، أو فصل الجلسات مع إظهار حالة واضحة لكل Profile. لكل بديل ثمن: الأول قد يكرر عملية غير آمنة، والثاني يخفي السبب عن المستخدم، والثالث يزيد تعقيد التنسيق. القرار قد يكون فصل الجلسات مع رسالة خطأ تفرّق بين «لا اتصال» و«جلسة منتهية»، لأن المستخدم يستطيع التصرف في الحالتين بشكل مختلف.
أما الاختبار فيُوصف بدقة: هل جرى في بيئة معزولة؟ هل حُاكي انقطاع الشبكة أم انتظروا وقوعه؟ وهل اختُبرت إعادة التشغيل بعد استعادة الاتصال؟ ويُذكر ما لم يُحل، مثل أن هذا لا يمنع رفضًا قادمًا من جهة خارجية، ولا يعوّض إعدادًا خاطئًا في سير العمل. هذا النوع من السرد يفيد مطورًا آخر حتى لو لم يستخدم Social Browser، لأنه يعلّمه كيفية تفكيك خطأ يبدو واحدًا إلى حالات مختلفة قابلة للمعالجة.
قالب من خمس فقرات لأي قرار هندسي
يمكن تحويل أي تحديث إلى مقال هندسي نافع عبر خمس فقرات قصيرة:
خطوات التطبيق
- **المشكلة:** ما الذي كان يحدث، لمن، وتحت أي قيود؟ ابدأ بوصف قابل للتحقق لا بشعار.
- **البدائل:** ما الحلول التي دُرست أو جُرّبت؟ ولماذا استُبعد كل بديل؟ ذكر البديل السيئ يمنح الثقة في القرار الجيد.
- **القرار:** ما الذي اختير فعلًا، وما الثمن الذي قُبل دفعه؟ القرار بلا ثمن يبدو دعاية لا هندسة.
- **الاختبار:** كيف تحقق الفريق؟ ما الأدوات والشروط؟ وما الذي لم يُختبر بعد؟
- **الدروس:** ما الذي لم يُحل؟ وما الذي ستفعله differently المرة القادمة؟
الفقرة الخامسة هي الأكثر إهمالًا والأكثر قيمة. بدلًا من «حسّنّا سرعة البروفايلات»، اكتب ما الذي كان بطيئًا، وكيف قيس الزمن، وما البدائل التي جُرّبت، وما الذي تحسّن ضمن ظروف محددة. إن لم تكن الأرقام موثقة، قل ذلك بوضوح ولا تخترعها. واختم بسؤال محدد يفتح النقاش، مثل: «أي بديل كنتم ستختارون لو تضاعف عدد البروفايلات التي تعمل في الوقت نفسه؟» السؤال المحدد أفضل من دعوة عامة للتعليق، لأنه يعطي القارئ مدخلًا حقيقيًا للتجربة.
كيف تجري تجربة توثيق مصرحًا بها
التوثيق الجيد لا يحتاج إلى كشف أسرار المشروع، لكنه يحتاج إلى انضباط. ابدأ بتحديد سؤال واحد تريد الإجابة عنه، ثم سجّل خط الأساس قبل أي تغيير. اكتب قائمة البدائل قبل التجربة، لا بعدها، حتى لا تعيد كتابة التاريخ وفق النتيجة التي تفضّلها. اختبر في بيئة معزولة وبإذن واضح، ولا تتدخل في بيانات مستخدمين حقيقية أو وظائف إنتاجية دون تفويض.
حدد مسبقًا معيار النجاح والفشل: ما الذي سيجعل الحل مقبولًا؟ وما الذي سيجعله مرفوضًا حتى لو بدا أفضل؟ بعد التجربة، احذف الأسرار وبيانات التعريف من أي مقتطف أو سجل، واكتب الحدود التي لم يختبرها الفريق. أخيرًا، أعطِ النص لشخص لم يشارك في العمل واسأله: ما المشكلة؟ ما البديلان الرئيسيان؟ لماذا رُفض أحدهما؟ فإن لم يستطع الإجابة، فالتوثيق لم يكتمل بعد.
أخطاء شائعة تفرغ المقال من قيمته
معايير تقييم: هل التوثيق قابل لإعادة التنفيذ؟
أفضل اختبار للتوثيق هو سؤال: هل يستطيع مطور خارج الفريق إعادة التجربة أو تقييم القرار؟ هذا يتطلب أربعة معايير. الأول قابلية إعادة التنفيذ: هل الشروط والأدوات ومعيار النجاح واضحة بما يكفي؟ الثاني إمكانية التتبع: هل كل قرار مرتبط بمشكلة وبديل وسبب؟ الثالث الصدق: هل ذُكر ما لم يُحل وما لم يُختبر؟ الرابع الاقتصاد: هل كل فقرة تضيف معلومة، أم تعيد الصياغة؟
يمكن تطبيق «اختبار القارئ الخارجي»: أعطِ النص لشخص لم يحضر التنفيذ، واطلب منه تلخيص المشكلة في جملة، وذكر بديلين، وتحديد ما سيدفع القرار إلى التراجع. إذا عجز عن ذلك، فالمشكلة في النص لا في القارئ. ولا يعني النجاح في هذا الاختبار أن القرار صحيح، بل أن النص يجعله قابلًا للنقد بإنصاف.
حدود التصميم وما لا يستطيع التوثيق فعله
التوثيق لا يعوّض الاختبار، ولا يصلح عيبًا معماريًا، ولا يمنح ضمانًا أمنيًا. كما أنه لا يقدم وعدًا بأن المنتج سيتجاوز كشف المنصات؛ ف ـSocial Browser أداة لإدارة Profiles وأتمتة سير العمل، وليست ضمانًا لتجاوز أنظمة الكشف. بعض القرارات تتأثر بقيود قانونية أو تجارية لا تظهر في الكود، ويجب أن يُقال ذلك صراحة بدل تقديمها كخيارات تقنية محضة.
كذلك تتقادم الوثائق: إصدار جديد قد يغيّر سلوكًا وصفه مقال قديم. لذلك يحتاج كل نص هندسي إلى تاريخ وسياق وإشارة إلى ما قد تغيّر. وأخيرًا، ليست كل التفاصيل قابلة للنشر؛ الحد الفاصل هو أن تشرح نمط القرار والقيود دون كشف بيانات المستخدمين أو الأسرار التشغيلية.
أسئلة شائعة وخلاصة عملية
هل يجب نشر كل التفاصيل الداخلية؟
لا. انشر المشكلة والبدائل ومعايير القرار والحدود، واحذف ما يخص بيانات المستخدمين أو الأسرار أو تفاصيل قد تسبب ضررًا. الشفافية المفيدة ليست تفريغًا كاملًا، بل شرحًا كافيًا ليفهم القارئ ويقارن.
ماذا لو لم تتوفر أرقام موثوقة؟
قل إن الأرقام غير متاحة، وصف ما لاحظه الفريق وصفًا نوعيًا، واذكر الظروف التي جعلت الملاحظة ممكنة. لا تحوّل الانطباع إلى قياس، ولا تستخدم صيغة الجزم حيث لا يوجد دليل.
ماذا لو اتضح أن القرار كان خاطئًا لاحقًا؟
وثّق التراجع كما وثّقت القرار الأول: ما الذي تغيّر؟ ما الإشارة التي كشفت الخطأ؟ ما البديل الجديد؟ المقال عن قرار فاشل قد يكون أنفع من مقال عن نجاح سلس، لأنه يعلّم القراءة الصحيحة للأدلة.
من يكتب التوثيق الهندسي؟
من اتخذ القرار أو شارك فيه، بمراجعة من شخص آخر. ليس ضروريًا أن يكون الكاتب متخصصًا في التحرير، لكن من الضروري أن يفهم الفرق بين وصف الميزة وشرح سببها.
خلاصة عملية
اكتب المشكلة قبل الحل، واذكر بديلًا رُفض ولماذا، وحدد ما لم تحله. اجعل الاختبار قابلًا للتكرار، وامنع الأرقام غير الموثقة، واختم بسؤال يفتح نقاشًا حقيقيًا. بهذه الطريقة يتحول كل تحديث هندسي إلى أصل معرفي، لا إلى إعلان ينتهي أثره في يوم النشر. ولمن يريد معرفة السياق الذي تُطرح فيه هذه الأفكار، يمكن زيارة الموقع العربي ل ـSocial Browser.
شارك في تقييم ونقاش المقال
رأيك يضيف قيمة للمقال ويساعدنا على تحسين المحتوى والنقاش حوله.
النقاش
جارٍ تحميل التعليقات…