المهارات المهنية للتقنيين الأدلة التقنية

كتابة توثيق يعود إليه القارئ: README ودليل التشغيل

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

كتابة توثيق يعود إليه القارئ: README ودليل التشغيل

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

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

سوف نناقش في هذا المقال:

  • لماذا لا يعود الناس إلى التوثيق، ومن هو القارئ الحقيقي لكل صفحة.
  • إطار Diátaxis وأنواع التوثيق الأربعة، ولماذا لا تخلط بينها.
  • كيف تكتب ملف README، ودليل التشغيل، ووثيقة التصميم، بقالب لكل منها وأمثلة قبل وبعد.
  • قواعد كتابة الجملة من أدلة الأسلوب المنشورة، ومبادئ مجتمع Write the Docs.
  • كيف تبقي التوثيق حياً وصحيحاً، وكيف تختبره، وكيف تكتبه بالعربية.

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

باختصار Quick Summary

💡
ابدأ بالقارئ: من سيقرأ هذه الصفحة، وما السؤال الذي جاء به، وفي أي ظرف؟
نوع واحد لكل صفحة: درس تعليمي Tutorial، أو دليل مهمة How-to، أو مرجع Reference، أو شرح Explanation.
README: ما هذا، ولمن، وكيف تشغله، ومن يملكه، وأين تجد المساعدة.
دليل التشغيل: خطوة واحدة في كل سطر، ومعها النتيجة المتوقعة، وما تفعله إذا لم تظهر.
وثيقة التصميم: السياق والأهداف والخيارات المرفوضة، لأن القارئ بعد سنة يسأل «لماذا؟».
أبقه حياً: غير التوثيق مع التغيير نفسه، واحذف الصفحة الميتة، ولكل صفحة مالك وتاريخ مراجعة.

لماذا لا يعود الناس إلى التوثيق؟ Why Docs Fail

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

  • الصفحة كتبت لقارئ آخر: مهندس جديد يريد أن يشغل الخدمة على جهازه، فيجد صفحة تشرح تاريخ المعمارية.
  • الصفحة تخلط أنواعاً: خطوات التثبيت في منتصف شرح طويل عن سبب اختيار التقنية، فلا يجدها من يبحث عن الخطوات، ويمل منها من يريد الشرح.
  • الصفحة قديمة: كتبت صحيحة ثم تغير النظام. وتقول مبادئ Write the Docs إن التوثيق الخاطئ أسوأ من التوثيق الغائب، لأن القارئ يثق به ويضيع وقته.
  • الصفحة لا تجد: موجودة في مكان لا يبحث فيه أحد، أو عنوانها لا يحتوي الكلمة التي يبحث بها الناس.
  • الصفحة طويلة دون ترتيب: الجواب موجود لكنه في الفقرة السابعة دون عنوان يدل عليه.

وكل سبب من هذه له علاج في الأقسام التالية. والعلاج الأول والأهم أن تعرف قارئك قبل أن تكتب سطراً.

من يقرأ توثيقك؟ Know Your Reader

قبل أن تكتب، اسأل ثلاثة أسئلة: من سيقرأ هذه الصفحة؟ وما السؤال الذي جاء به؟ وفي أي ظرف سيقرؤها؟ فالمهندس الجديد في أسبوعه الأول يقرأ بهدوء ويريد أن يفهم. والمناوب On-call الذي استيقظ على تنبيه Alert في الثالثة فجراً يريد خطوات لا يحتاج أن يفكر فيها. والمهندس من فريق آخر يريد أن يعرف كيف يستخدم خدمتك فقط، ولا يهمه كيف بنيت.

خمسة قراء لتوثيق خدمة واحدة، لكل منهم سؤال وظرف ووثيقة: المهندس الجديد يسأل كيف أشغلها على جهازي ويحتاج درساً أو README، والمناوب في منتصف الليل يسأل ماذا أفعل الآن ويحتاج دليل التشغيل، ومستخدم الخدمة من فريق آخر يسأل كيف أستدعيها ويحتاج المرجع، والمراجع يسأل هل التصميم سليم ويحتاج وثيقة التصميم، وأنت بعد سنة تسأل لماذا فعلنا هذا وتحتاج سجل القرار
خدمة واحدة وخمسة قراء: كل قارئ يأتي بسؤال مختلف ويحتاج صفحة مختلفة
القارئسؤالهظرفهما يحتاجه
مهندس جديد في الفريقكيف أشغل الخدمة وأفهمها؟عنده وقت، ولا يعرف المصطلحاتملف README ودرس تعليمي قصير
المناوب On-callماذا أفعل الآن؟متعب ومستعجل وتحت ضغطدليل التشغيل Runbook
مستخدم من فريق آخركيف أستخدم الخدمة؟يريد الجواب ثم يعود لعملهالمرجع Reference ودليل مهمة
مراجع التصميمهل الحل سليم، وما البدائل؟يقرأ بعناية وينتقدوثيقة التصميم Design Doc
أنت أو زميلك بعد سنةلماذا يبدو النظام هكذا؟يريد أن يغير شيئاً دون أن يكرر خطأسجل القرار ADR والشرح

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

أنواع التوثيق الأربعة: إطار Diátaxis

إطار Diátaxis الذي وضعه Daniele Procida طريقة مشهورة لترتيب التوثيق، وتستخدمه مشاريع مفتوحة المصدر كثيرة. وفكرته أن القارئ يأتي إلى التوثيق بأحد أربعة احتياجات مختلفة، ولكل احتياج نوع من الكتابة: الدرس التعليمي Tutorial، ودليل المهمة How-to Guide، والمرجع التقني Reference، والشرح Explanation. ويقترح أن يرتب التوثيق نفسه حول هذه الاحتياجات الأربعة.

مربع من أربعة أنواع للتوثيق حسب إطار Diataxis: الدرس التعليمي للتعلم بالتطبيق مثل شغل الخدمة أول مرة، ودليل المهمة لإنجاز عمل محدد مثل كيف تضيف عميلاً تجريبياً، والمرجع للمعلومة الدقيقة مثل قائمة الإعدادات وقيمها، والشرح للفهم مثل لماذا نستخدم طابور رسائل، مع محورين: التطبيق مقابل الفهم، والتعلم مقابل العمل
أربعة احتياجات وأربعة أنواع: لا تخلط بينها في صفحة واحدة
النوعسؤال القارئشكل الكتابةمثال من خدمة داخلية
الدرس التعليمي Tutorialعلمني من البدايةخطوات تقود المبتدئ إلى نتيجة تعمل، دون خيارات كثيرة«شغل خدمة الطلبات على جهازك وأنشئ أول طلب»
دليل المهمة How-toكيف أفعل هذا الشيء المحدد؟خطوات لهدف واحد، لقارئ يعرف الأساسيات«كيف تضيف طريقة دفع جديدة»
المرجع Referenceما القيمة أو التفصيل الدقيق؟قوائم وجداول كاملة ومرتبة، دون شرح طويل«الإعدادات Configuration وقيمها الافتراضية»
الشرح Explanationلماذا هو هكذا؟نص يشرح السبب والسياق والبدائل«لماذا نرسل الإشعارات عبر طابور رسائل»

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

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

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

ملف README: باب الخدمة

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

وموقع Make a README يقترح أقساماً لمشاريع المصادر المفتوحة، منها الاسم والوصف والتثبيت والاستخدام والدعم والمساهمة والترخيص وحالة المشروع. أما الخدمة الداخلية في شركتك فتحتاج أقساماً قريبة، مع أشياء لا يحتاجها مشروع مفتوح، مثل الفريق المالك ولوحات المراقبة:

صفحة README لخدمة داخلية مقسمة إلى أقسام بالترتيب: ما هذه الخدمة في جملتين، ثم من يملكها وكيف تتواصل معهم، ثم كيف تشغلها على جهازك، ثم كيف تنشر، ثم ما تعتمد عليه من خدمات، ثم أين السجلات ولوحات المراقبة، ثم روابط أدلة التشغيل وسجلات القرار، مع ملاحظة أن أول قسمين يجيبان عن أغلب الأسئلة
README لخدمة داخلية: أول قسمين يجيبان عن أغلب أسئلة الزائر
القسمماذا تكتبطوله
ما هذه الخدمة؟ماذا تفعل، ولمن، وما الذي لا تفعلهجملتان أو ثلاث
الفريق المالك Ownerاسم الفريق، وقناة التواصل، ومن المناوبثلاثة أسطر
التشغيل المحلي Local Setupالمتطلبات، والخطوات حتى تعمل الخدمة على جهازكقائمة مرقمة
الاختبارات Testsكيف تشغلها، وماذا تعني النتيجةسطران
النشر Deploymentكيف تصل التغييرات إلى الإنتاج، ومن يوافقفقرة أو رابط
الاعتماديات Dependenciesالخدمات وقواعد البيانات التي تحتاجهاقائمة
المراقبة Monitoringروابط السجلات Logs ولوحات المراقبة Dashboards والتنبيهاتروابط
روابط أخرىأدلة التشغيل، وسجلات القرار، ووثائق التصميمروابط

وأهم قسمين هما الأولان. فأغلب من يفتح README يريد أن يعرف ما هذه الخدمة ومن يسأل عنها. وهذا مثال افتراضي لأول فقرة قبل وبعد:

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

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

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

دليل التشغيل Runbook: لقارئ متعب ومستعجل

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

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

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

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

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

وثيقة التصميم Design Doc: للقارئ الذي يأتي بعد سنة

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

ويقول Malte Ubl في مقاله Design Docs at Google إن أهم الأقسام في الوثيقة السياق، والأهداف وما ليس هدفاً Non-goals، والخيارات الأخرى التي نظر فيها الفريق ولماذا رفضها. وهذه بالضبط الأقسام التي يبحث عنها قارئ السنة القادمة.

ولذلك اكتب قسم السياق بحيث يفهمه من لم يكن في الفريق يومها. وهذا مثال افتراضي:

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

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

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

صفحة حل المشكلات Troubleshooting

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

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

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

ملاحظات الإصدار ودليل الترحيل Release Notes and Migration Guides

إذا كانت خدمتك يستخدمها فريق آخر أو عملاء، فهناك نوعان آخران من التوثيق يقرؤهما الناس فعلاً، لأنهما يخبرانهم بما يمسهم مباشرة.

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

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

كم يطول التوثيق؟ Length

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

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

الذكاء الاصطناعي في كتابة التوثيق AI Drafts

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

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

قواعد الجملة: ما تقوله أدلة الأسلوب Style Guides

شركات كبيرة نشرت أدلة أسلوب Style Guides لتوثيقها، أشهرها دليل Google لأسلوب توثيق المطورين ودليل Microsoft للكتابة. وهي مكتوبة للإنجليزية، لكن أغلب قواعدها المهمة تنفع بالعربية. ومن أبرز ما في صفحة الخلاصة في دليل Google: أن تكون لغتك ودودة وقريبة من الحديث دون أن تكون هزلية، وأن تخاطب القارئ مباشرة بضمير «أنت»، وأن تستخدم المبني للمعلوم Active Voice حتى يكون واضحاً من يفعل الفعل، وأن تضع الشرط قبل التعليمة، وأن تستخدم القوائم المرقمة للخطوات المتتابعة.

وهذه القواعد مع أمثلة عربية قبل وبعد:

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

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

مبادئ Write the Docs Principles

مجتمع Write the Docs مجتمع عالمي لمن يكتبون التوثيق التقني، وينشر دليلاً مفتوحاً فيه مبادئ للتوثيق الجيد. وهذه أهمها لفريق تقني، مع ما تعنيه عملياً:

المبدأمعناه كما في الدليلما تفعله
سهل المسح Skimmableرتب المحتوى حتى يتجاوز القارئ ما يعرفه أو لا يحتاجهعناوين واضحة، وقوائم، وفقرات قصيرة
فيه أمثلة Exemplaryكثير من القراء يبحثون عن المثال أولاًمثال للحالات الأكثر شيوعاً، لا لكل حالة
صحيح الآن Currentالتوثيق الخاطئ أسوأ من الغائبغير التوثيق مع التغيير نفسه
قريب من الكود Nearbyاحفظ التوثيق أقرب ما يمكن إلى ما يوثقهREADME في المستودع، وليس في مجلد منسي
غير مكرر Uniqueلا تجعل نفس المحتوى في مصدرينصفحة واحدة لكل معلومة، والباقي روابط
يمكن إيجاده Discoverableضع إشارات إليه في كل مكان قد يبحث فيه القارئروابط من التنبيهات ومن قناة الفريق
له عنوان Addressableروابط مباشرة إلى أقسام محددةعناوين فرعية يمكن الربط إليها
تقبل بعض التكرار ARIDAccept (some) Repetition In Documentationكرر المعلومة القصيرة إذا كانت توفر على القارئ الانتقال بين صفحات

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

كيف يبقى التوثيق حياً؟ Keep Docs Alive

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

  1. الحد الأدنى من التوثيق Minimum Viable Documentation: مجموعة صغيرة من الوثائق الصحيحة والحديثة أفضل من مجموعة كبيرة في حالات مختلفة من الإهمال. واكتب وثائق قصيرة ومفيدة، واحذف كل ما هو قديم أو خاطئ أو مكرر.
  2. غير التوثيق مع الكود: عدل التوثيق في نفس التغيير الذي يعدل الكود. فهذا يبقيه حديثاً، ويشرح للمراجع ما تفعله. والمراجع الجيد يستطيع أن يطلب تحديث README والتوثيق مع التغيير.
  3. احذف التوثيق الميت Dead Documentation: الوثائق الميتة تضلل القارئ وتبطئه. وإذا كانت وثائقكم في حالة سيئة فابدأ ببطء، واحذف أولاً ما أنت متأكد أنه خاطئ، واطلب من الفريق كله أن يمر على الوثائق ويقرر لكل واحدة: نبقيها أم نحذفها؟
  4. الجيد أفضل من الكامل: لا توجد وثيقة كاملة. والوثيقة الجيدة التي تنشر اليوم أفضل من الكاملة التي لا تنشر.
دورة حياة الوثيقة في حلقة: تكتب مع التغيير نفسه، ثم تراجع مع مراجعة الكود، ثم تستخدم ويسجل كل سؤال لم تجب عنه، ثم تراجع في تاريخ المراجعة بواسطة مالكها، ثم تحدث أو تحذف، ومن الحلقة سهم إلى الحذف للصفحة الميتة
الوثيقة الحية: تكتب مع التغيير، وتراجع في موعدها، وتحذف حين تموت

ويضاف إلى هذه القواعد عادتان بسيطتان. الأولى أن يكون لكل صفحة مالك Owner وتاريخ مراجعة Review Date مكتوبان في أعلاها، حتى يعرف القارئ هل يثق بها، ويعرف المالك متى يعود إليها. والثانية أن يحتفظ الفريق بالتوثيق في نفس المستودع مع الكود متى أمكن، وهو ما يسمى التوثيق ككود Docs as Code، حتى يمر تغيير التوثيق بنفس المراجعة التي يمر بها الكود. ويشرح Write the Docs هذه الطريقة في صفحة Docs as Code.

من يكتب التوثيق؟ Who Writes

في كثير من الفرق يبقى التوثيق عمل «من عنده وقت»، فلا يكتبه أحد. أو يصبح عمل شخص واحد يحب الكتابة، فيكتب كل شيء، ثم يغادر الفريق فتموت الصفحات معه. وكلا الحالين خطأ.

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

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

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

التوثيق في مراجعة الكود Docs in Code Review

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

وبعض الفرق تضيف هذا السؤال إلى قالب طلب الدمج Pull Request Template كخانة يضع فيها الكاتب علامة: «حدثت التوثيق» أو «لا يحتاج تحديثاً». والخانة البسيطة تذكر الكاتب والمراجع معاً، وتجعل نسيان التوثيق قراراً واعياً وليس سهواً.

كيف تختبر التوثيق؟ Testing Docs

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

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

التوثيق بالعربية Arabic Docs

إذا كان فريقك يكتب التوثيق بالعربية، أو جزءاً منه، فهناك أشياء خاصة بالعربية تستحق الانتباه:

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

كيف تكتب أول README لخدمتك اليوم؟ Steps

إذا كانت عندك خدمة بلا README جيد، فهذه خطوات تكفيها ساعة أو ساعتان:

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

أخطاء شائعة Common Mistakes

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

قائمة تحقق قبل أن تنشر الصفحة Checklist

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

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

دليلثقافة الكتابة في الفريق Writing Culture: RFC وADRكيف يكتب الفريق الفكرة قبل أن يناقشها، ومتى يكتب طلب نقاش أو سجل قرار، ومتى يكون الاجتماع أفضل من الوثيقة.دليلرسائل العمل التي تقرأ فعلاً: Email وChat والتذاكركيف تكتب بريداً ورسالة محادثة وتذكرة يفهمها القارئ من أول سطرين ويرد عليها بسرعة، مع أمثلة قبل وبعد.دليلكيف تشرح عملك التقني لغير المختصين Non-technicalكيف تشرح عملك التقني للعميل والإدارة والمبيعات والقانوني وأهلك بطبقات وتشبيهات ولغة واضحة، مع أمثلة قبل وبعد.دليلدليل التشغيل Runbook: وثق الإجراء قبل أن تحتاجهنكتب دليل تشغيل لقاعدة بيانات امتلأ قرصها، ثم ننفذه بالثواني في يوم تجربة، فنكتشف فيه خطأين لم يظهرا إلا عند التنفيذ.دليلتوثيق المعمارية: مخططات C4 وسجلات القرارات المعمارية ADRكيف ترسم نظامك بمخططات C4 يفهمها المطور الجديد، وتحفظ سبب كل قرار مهم في سجل ADR داخل المستودع.دليلقاعدة معرفة الفريق Wiki: نظمها ليجد الناس ما يبحثون عنهلماذا تضيع معرفة الفريق في المحادثة، وكيف تبني Wiki لها مالك ومراجعة وبحث يفهم الكلمات العربية، مع مختبر يقيس البحث العربي في PostgreSQL.دليلالعمل غير المرئي Glue Work: كيف يظهر ويحسب لكما هو العمل اللاصق الذي يربط الفريق، ولماذا لا يظهر في التقييم، وكيف تجعله مرئياً وتأخذ منه نصيبك العادل فقط.

الخلاصة

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

سجل التحديثات

  • 2026-11-19: كتابة المقال، والتحقق من موقع Diátaxis، ودليل Write the Docs ومبادئه، ودليل Google لأفضل ممارسات التوثيق ودليل أسلوب المطورين، ودليل Microsoft، وصفحة GitHub عن README، وموقع Make a README، ومقال Malte Ubl من مصادرها في نفس التاريخ.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.