الوثائق التقنية ليست مهمة جانبية تنهيها بعد اكتمال عملية تجميع الكود (compilation). بل هي تقع في قلب كل مشروع برمجيات، وهي التي تحدد ما إذا كان المطور الجديد سيتمكن من إصلاح خطأ ما في يومه الأول، أو ما إذا كان المستخدم سيترك منتجك بعد خمس دقائق من الارتباك. التوثيق الجيد يساعد المستخدمين على إنجاز مهام حقيقية، ويساعد القائمين على الصيانة مستقبلاً على فهم سبب وجود وحدة برمجية معينة وكيفية تغييرها دون كسر كل شيء. ومع ذلك، تتعامل الكثير من الفرق مع التوثيق كأمر ثانوي، أو مجرد ملف README تم إعداده على عجل، أو صفحة ويكي تُركت لتندثر. إن كتابة توثيق مفيد حقاً هي مهارة يمكنك تحسينها عن قصد.
تعرف على قرائك قبل أن تبدأ الكتابة
قبل أن تكتب عنواناً واحداً، قرر من الذي يقرأ. فمدير قاعدة البيانات الذي يبحث عن إعدادات مجمع الاتصالات (connection pool) لا يجمعه أي شيء مشترك مع مطور واجهات أمامية (front-end developer) يبحث عن خصائص مكونات React. يحتاج المستخدمون النهائيون إلى خطوات مرقمة ولقطات شاشة، وليس إلى مخططات معمارية؛ فهم يريدون معرفة كيفية تصدير ملف PDF، وليس كيفية عمل خط معالجة الرندرة (rendering pipeline). أما المطورون الذين يدمجون مكتبتك، فيحتاجون إلى تواقيع دوال (function signatures) دقيقة، ورموز خطأ، ومقتطفات برمجية جاهزة للنسخ واللصق. بينما يحتاج مسؤولو الأنظمة إلى متطلبات التثبيت المسبقة، ومتغيرات البيئة، ومسارات استكشاف الأخطاء وإصلاحها التي تبدأ من أكثر حالات الفشل شيوعاً.
إذا حاولت خدمة المجموعات الثلاث جميعها عبر كتلة نصية واحدة، فسيخسر الجميع. أنشئ مسارات منفصلة. حتى الصفحة الواحدة يمكن تقسيمها بوضوح باستخدام عناوين مثل "للمشغلين" و"لمطوري العميل". الهدف هو إزالة الاحتكاك الذهني الناتج عن التساؤل: "هل هذه الفقرة موجهة لي؟"
تخلص من الحشو
الوضوح يتفوق على التكلف. استخدم جملاً قصيرة، واستخدم صيغة المبني للمعلوم. عبارة "قم بتهيئة قاعدة البيانات" أوضح من "يجب أن يتم تهيئة قاعدة البيانات من قبل المستخدم". عندما تضطر لاستخدام مصطلح تقني مثل "idempotency" أو "serialization"، فقم بتعريفه ضمن السياق أو اربطه بمسرد للمصطلحات. لا تفترض وجود معرفة مسبقة لدى القارئ.
اختبار عملي واحد: حاول قراءة فقرتك بصوت عالٍ. إذا نفد نفسك، فالجملة طويلة جداً. اختبار آخر: استبدل الأفعال المزخرفة بأخرى بسيطة. إذا كان من الممكن تحويل عبارة مثل "استخدم الـ API" بدلاً من "قم بالاستفادة من الـ API" دون فقدان المعنى، فقم بإجراء التغيير. اللغة البسيطة لا تعني اللغة السطحية، بل تعني اللغة الدقيقة المجردة من الحشو المؤسسي.
هيكلية مفيدة حقاً
الدليل غير المنظم يهدر من الوقت أكثر مما يفعله عدم وجود دليل على الإطلاق. فكر في توثيقك كقمع (funnel). في الأعلى، ضع نظرة عامة قصيرة تشرح ما يفعله المشروع ومن يجب أن يهتم به. اتبع ذلك بتعليمات التثبيت التي لا تفترض أي شيء عن إعدادات القارئ المحلية. ثم أضف دروساً تعليمية (tutorials) تأخذ المستخدم عبر سيناريوهات كاملة وواقعية من البداية إلى النهاية. تأتي بعد ذلك مراجع الـ API، والتي يجب أن تكون شاملة ولكن سهلة التصفح، ومجمعة حسب المورد أو الوظيفة بدلاً من سردها عشوائياً بترتيب أبجدي. وأخيراً، ضع أدلة استكشاف الأخطاء وإصلاحها التي تعالج أعراضاً محددة. فالمستخدم الذي تظهر له رسالة "Connection refused" يحتاج إلى إجابة تختلف عن المستخدم الذي يرى "Permission denied". قم بتجميع الأخطاء حسب الرسالة أو السياق، وليس حسب فئة مجردة.
تساعد القوائم والكتل البرمجية (code blocks) في كسر جمود النصوص الكثيفة وتسمح للقراء بالبحث عن الأمر الدقيق الذي يحتاجونه. يمكن لقائمة نقطية موضوعة جيداً أن تحول فقرة من الارتباك إلى تسلسل من الإجراءات الواضحة.
اعرض ولا تكتفِ بالشرح
الشروحات المجردة تثير إحباط المستخدمين. إذا كنت تصف كيفية تهيئة أداة ما، فأظهر المحتويات الدقيقة للملف. قدم مقتطفات برمجية للتثبيت، وللتهيئة، وللتكوينات الشائعة. اعرض مدخلات نموذجية والمخرجات المتوقعة جنباً إلى جنب. إذا كانت الـ API الخاصة بك تعيد JSON، فأظهر الـ JSON. إذا كانت أداة CLI تنتج مخرجات في شكل جدول، فأظهر الجدول. لا تثق أبداً بأن وصف سير العمل يعادل العرض العملي.
والأهم من ذلك، اختبر كل مثال في بيئة نظيفة قبل نشره. انسخ مقتطفك البرمجي الخاص وضعه في حاوية (container) جديدة أو جهاز افتراضي (virtual machine). إذا فشل المثال لأنك نسيت ذكر أحد التبعيات (dependency)، فقد وفرت على نفسك سيلاً من المشكلات. توفر الأمثلة الملموسة أكبر عائد على الاستثمار في الكتابة التقنية لأنها تحول عدم اليقين إلى إجراء فعلي.
حافظ على حيوية التوثيق
التوثيق يتآكل أسرع من الكود. يتغير توقيع دالة، أو ينتقل منفذ افتراضي، أو تُستبدل تبعية ما، وفجأة تجد تعليماتك قد قادت المستخدم إلى طريق مسدود.