4.6 مقاييس التوثيق والمعرفة

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

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

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

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

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

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

التوصيات

تتبّع وصول التوثيق وتقادمه، لا الوجود فقط

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

راقب الأسئلة المتكررة كإشارة قابلية اكتشاف

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

قِس وقت الإدماج لأول مساهمة ذات معنى ومستقلة

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

حدِّد وأعطِ أولوية لمجالات معرفة حرجة غير موثقة صراحة

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

عامل ديون التوثيق كفئة داخل قائمة انتظار ديونك التقنية

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

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

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

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

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

بالنسبة لأخطر أنظمتنا وأقلها عامل حافلة، هل يوجد توثيق ذو معنى ودقيق فعليًا، أم سيأخذ خبير مغادر معظم المعرفة الحقيقية معه؟ هذا أوضح وأكثر نسخة ملموسة من الاهتمام المركزي لهذا الموضوع؛ أجب عنه بصدق لأخطر نظام لديك أولًا.
أي سؤال يُطرَح مرارًا في دردشة فريقنا رغم وجود إجابة موثقة في مكان ما؟ إذا كنت تستطيع تسمية واحد فورًا، تلك مشكلة قابلية اكتشاف تستحق الإصلاح مباشرة، على الأرجح بإعادة تنظيم أو كشف المحتوى الحالي بشكل أفضل بدلًا من كتابة المزيد.
كم استغرق أحدث عضو فريق جديد لديه ليقدّم مساهمته الأولى ذات المعنى والمستقلة، وكيف قورن ذلك بعضو الفريق قبله؟ تباين كبير وغير مُفسَّر بين الأفراد غالبًا ما يشير إلى معرفة تعتمد بشدة على من يُدمِج شخصًا بالصدفة، بدلًا من توثيق دائم وقابل للوصول.
متى تحققنا آخر مرة من أن قطعة توثيق لا تزال دقيقة، نسبة لكم تغيّر النظام الأساسي منذ كتابتها؟ إذا كانت الإجابة الصادقة “لا نتحقق من هذا منهجيًا”، خطر التقادم ذلك على الأرجح أكبر مما يفترض أي أحد حاليًا.
هل تشمل قائمة انتظار ديوننا التقنية (الموضوع 4.5) فجوات توثيق، أم يُؤجَّل عمل التوثيق باستمرار كمهمة أقل مكانة مقارنة بإصلاحات الكود؟ تحقق من قائمة انتظارك الفعلية وانظر ما إذا كانت ديون التوثيق مرئية وتتنافس على قدرة ذات أولوية أو غير مرئية فعليًا.
كم سيكلّفنا لو غادر الشخص أو الشخصان اللذان يفهمان أخطر أنظمتنا وأقلها توثيقًا خلال نفس العام؟ هذا السؤال الملموس وغير المريح يستحق الإجابة عنه بصدق بدلًا من معاملة الخطر كمجرد أو غير مُحتمَل.

منظور القطاع

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

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

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

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

أمثلة

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

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

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

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

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

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

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

نموذج النضج

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

أفكار للنقاش

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

أهم الاستنتاجات

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

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

Docs for Developers: An Engineer’s Field Guide to Technical Writing، بقلم Jared Bhatti وZachariah Goldberg وTed Kubaska وSarah Moir (ممارسات توثيق عملية لفرق الهندسة).
A Philosophy of Software Design، بقلم John Ousterhout (العلاقة بين التوثيق، والتعقيد، وقابلية الصيانة).
Team Topologies، بقلم Matthew Skelton وManuel Pais (تبعات التصميم التنظيمي لمعرفة مُركَّزة مقابل موزَّعة).
Accelerate: The Science of Lean Software and DevOps، بقلم Nicole Forsgren وJez Humble وGene Kim (التوثيق كواحدة من القدرات المرتبطة بأداء التسليم).