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

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

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

لماذا يتقادم التوثيق

ثلاث آليات، وواحدة منها فقط هي الكسل.

التوثيق يعيش بعيداً عن الشيء الذي يصفه. تغيير الشيفرة ليس تغييراً لصفحة ويكي، لذا يبقى التوافق بينهما رهيناً بأن يتذكر أحدهم. تلك الذاكرة تخذلنا بانتظام يمكن الاعتماد عليه، وكلما جلس المستند أبعد عن الشيفرة كان تقادمه أسرع.

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

لا مالك له. التوثيق الذي يملكه الجميع لا يملكه أحد، ولا توجد لحظة واحدة تصبح فيها دقته مشكلة شخص بعينه.

العلاجات تنبع من الأسباب مباشرة: أبقِ التوثيق قريباً من الشيفرة، واكتب النية بدل الآلية، وامنح كل مستند مالكاً باسمه وسبباً حقيقياً يجعل أحداً يستخدمه بالفعل.

التوثيق التقني الذي يستحق الصيانة

أربعة مستندات تغطي معظم القيمة. وكل ما عداها عليه أن يبرر وجوده.

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

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

سجلات القرارات. ملاحظات قصيرة تثبّت قراراً، والبدائل التي دُرست، وسبب الاختيار. يسميها أهل المهنة عادة Architecture Decision Record، أو ADR اختصاراً. يُضاف إليها ولا تُحدَّث أبداً، وهي تمنع أغلى أنواع العمل المكرر: إعادة الجدال بشكل رديء حول مسألة محسومة، لأن أحداً لم يعد يذكر القيد الذي حسمها في حينه.

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

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

اكتب لشخص مرهق ومستعجل

معظم التوثيق التقني يُقرأ تحت الضغط، من شخص لديه سؤال محدد جداً، وغالباً خارج ساعات العمل. اكتب لهذا القارئ، لا لقارئ متفرغ يقرأ على مهل.

أجب أولاً واشرح بعد ذلك. من يقرأ دليل التشغيل عندك في الثانية بعد منتصف الليل يحتاج الأمر أولاً ثم التعليل بعده. وضع السياق قبل الجواب بنية تناسب الكاتب ولا تناسب أحداً غيره.

كن محدداً. أوامر حقيقية، ومسارات حقيقية، وقيم أمثلة حقيقية. عبارة «اضبط متغيرات البيئة المناسبة» ليست تعليمة، بل وصف لتعليمة.

قل ما الذي سيسوء. أنماط الأعطال وشكلها هي في الغالب أثمن محتوى في الصفحة كلها، لأنها بالضبط ما يعيشه القارئ في تلك اللحظة.

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

الانضباط نفسه الذي يجعل الصفحة قابلة للاقتباس أمام نظام استرجاع هو ما يجعلها صالحة للاستخدام أمام زميل منهك، وهذا تحديداً ما يقوله دليلنا عن لماذا يتصدر محتواك الترتيب ولا يُقتبس أبداً بخصوص النصوص العامة.

كيف تبقيه حياً

ضعه داخل المستودع. المستند الذي يسافر مع الشيفرة يُعدَّل في المراجعة نفسها التي تُعدَّل فيها الشيفرة، وهذه هي الآلية الوحيدة التي تبقي الاثنين متوافقين بشكل موثوق.

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

اختبر ما يمكن اختباره. تعليمات التهيئة التي تُنفَّذ داخل خط إنتاج تتوقف عن كونها أمنيات. إذا ادّعى ملف README عندك أن ثلاثة أوامر تنتج نظاماً يعمل، فاجعل مهمة آلية تثبت ذلك.

احذف بلا تردد. المستند الخاطئ أسوأ من المستند الغائب، لأن الناس يثقون به. حين يتقادم شيء ولن يصلحه أحد، أزله ودوّن ما الذي ضاع معه.

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

ما الغرض الحقيقي من هذا

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

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

تكتب Mecanik هذه المستندات ضمن التسليم في كل مشروع، كجزء من عملنا في تطوير البرمجيات. والمستند الذي يُستخدم فعلاً يكون دائماً تقريباً أقصر من المستند الذي طُلب في البداية.

الأسئلة الشائعة

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

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

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

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

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