2.7 التوثيق

نظرة عامة والدافع

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

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

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

المبادئ الأساسية

اكتب من أجل قارئ محدد بحاجة محددة؛ أنواع التوثيق المختلفة تخدم أغراضًا مختلفة.
أبقِ التوثيق قريبًا من الشيفرة وعامله كشيفرة (التوثيق كشيفرة).
الدقة تتفوق على الاكتمال؛ قدر صغير من التوثيق الجدير بالثقة أفضل من قدر كبير خاطئ.
ولّد ما يمكن توليده؛ لا تصُن يدويًا ما تستطيع أداة إنتاجه من مصدر الحقيقة.
قاوم تعفن التوثيق بنشاط؛ التوثيق المتقادم أسوأ من عدمه لأنه يضلل.
اجعل التوثيق قابلًا للاكتشاف؛ المعرفة غير القابلة للإيجاد غائبة فعليًا.
سجّل القرارات ومبرراتها، لا الحالة الحالية فقط.

التوصيات

تبنَّ التوثيق كشيفرة

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

هيكل المحتوى بإطار Diátaxis

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

صُن الوثائق التشغيلية الأساسية

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

ولّد توثيق واجهة البرمجة وسجلات التغيير من مصدر الحقيقة

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

سجّل قرارات العمارة

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

قاوم تعفن التوثيق عمدًا

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

استثمر في إدارة المعرفة وقابلية الاكتشاف

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

المفاضلات: الإيجابيات والسلبيات

النهج	الإيجابيات	السلبيات
التوثيق كشيفرة	مُصدَر، قابل للمراجعة، قريب من الشيفرة؛ تعفن منخفض	يتطلب انضباط المهندس؛ أقل ودية للمؤلفين غير التقنيين
ويكي / قاعدة معرفة	سهل التحرير؛ متاح للجميع	ينحرف عن الشيفرة؛ يتشظى؛ يتعفن بصمت
توثيق مولَّد (واجهة برمجة، سجل تغييرات)	دقيق دائمًا؛ صيانة منخفضة	محدود بما يعبّر عنه المصدر؛ يحتاج أدوات
شرح مكتوب يدويًا	سياق ومبرر غنيان لا تستطيع الآلات إنتاجهما	كثيف العمالة؛ عرضة للتقادم
بنية Diátaxis	غرض واضح لكل صفحة؛ أسهل في التصفح والصيانة	جهد هيكلة مسبق؛ يتطلب انضباط المؤلف

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

أسئلة للنقاش مع فريقك

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

المنظور القطاعي

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

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

المؤسسة الكبرى. عبر فرق كثيرة، المشكلة هي الاتساق وقابلية الاكتشاف: خط أنابيب توثيق كشيفرة مشترك، وبنية موحدة مثل Diátaxis، ومراجع واجهة برمجة وسجلات تغيير مولَّدة، وسجلات قرار مطبَّقة بالطريقة نفسها في كل مكان بحيث لا تتشظى المعرفة عبر عشرات الويكيات. عيّن ملكية لكل وثيقة عالية القيمة وقِس الدقة، لا الوجود فقط. عامل سجلات العمارة وأدلة التشغيل وسجلات القرار كدليل تدقيق، ووحّد كيفية إنتاجها بحيث تجد مراجعة ضبط مسارًا موثقًا ومدافَعًا عنه بدل تخبط.

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

أمثلة

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

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

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

حالة العمل: الدوافع والعائد على الاستثمار وتكلفة الملكية الإجمالية

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

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

الأنماط المضادة والمزالق

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

نموذج النضج

المستوى 1، الشروع. التوثيق نادر ومبعثر ومتقادم، والمعرفة تعيش في رؤوس الناس. ما هو موجود كُتب مرة ولم يُلمَس أبدًا مجددًا، بحيث يعني انقطاع أو رحيل هندسة عكسية للنظام.
المستوى 2، التطوير. توجد وثائق رئيسية، مثل ملفات README وبضعة أدلة تشغيل، لكنها تُصان بتفاوت ويصعب إيجادها. توثق بعض الفرق جيدًا وأخرى بالكاد، ولا يوجد توقع مشترك بشأن ما ينبغي أن يحمله مستودع أو أين ينبغي أن يعيش.
المستوى 3، التوحيد القياسي. التوثيق كشيفرة هو المعيار عبر المؤسسة: بنية موحدة مثل Diátaxis، ومراجع واجهة برمجة وسجلات تغيير مولَّدة، وسجلات قرار، وتوقع في المراجعة بأن تتغير الوثائق مع الشيفرة التي تصفها. لكل وثيقة عالية القيمة مالك مسمى، ويوجد موطن واحد معروف ببحث حقيقي.
المستوى 4، الإدارة. يُقاس التوثيق، لا مجرد وجوده. تتبع تغطية الوثائق الأساسية، ومعدل تغيير الوثائق مقابل معدل تغيير الشيفرة، وزمن الإلحاق، وحل الحوادث من أدلة التشغيل وحدها، والحداثة مقابل عتبة تقادم محددة، وتراجع تلك المقاييس مقابل خطوط أساس. يُكتشَف التعفن آليًا عبر التوليد، والاختبارات مقابل النظام، وفحوصات الروابط والدقة، وتُوسَم الصفحات المتقادمة أو تُشذَّب بالأدلة لا بالصدفة.
المستوى 5، التنسيق الشامل. يُحسَّن التوثيق باستمرار ويُدمَج عبر المؤسسة: حي، ومولَّد إلى حد كبير أو مختبَر مقابل النظام، ومملوك، وقابل للاكتشاف، ومتكيف. تغذي المقاييس أين تستثمر، وتُلتقَط المعرفة الضمنية كجزء روتيني من العمل، وتُعاد موازنة المجموعة وتُشذَّب بنشاط مع تغيّر الأنظمة والفرق والقراء.

أفكار للنقاش

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

النقاط الرئيسية

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

المراجع والقراءات الإضافية

Daniele Procida, Diátaxis documentation framework
Andrew Etter, Modern Technical Writing
Anne Gentle, Docs Like Code
Google, Developer Documentation Style Guide and Season of Docs guidance (as reference exemplars)
Michael Nygard, Documenting Architecture Decisions (architecture decision records)
Andrew Hunt and David Thomas, The Pragmatic Programmer (on knowledge and documentation)
Keep a Changelog (as a reference convention)