أفضل طريقة لإدارة الوثائق في عام 2027
فالوثائق هي جزء من مشروع يوافق الجميع على الأمور ولا أحد يتفق تماما على كيفية تناوله. انظر إلى خمسة مشاريع مفتوحة المصدر وستجد خمسة اعدادات مختلفة. بعضها ي
فالوثائق هي جزء من مشروع يوافق الجميع على الأمور ولا أحد يتفق تماما على كيفية تناوله. انظر إلى خمسة مشاريع مفتوحة المصدر وستجد خمسة اعدادات مختلفة. بعضها يعمل بشكل جيد. تنزلق أكثر من غيرها إلى الإهمال.
هذا ما تبدو عليه الأنماط الشائعة في الواقع العملي، ولماذا يتمسك البعض بشكل أفضل من الآخرين مع مرور الوقت.
نهج ويكي: سريع للبدء، بطيء للموت
GitHub wikis و Confluence هما الافتراضي لكثير من الأفرقة. إنها سريعة في الإعداد، لا توجد إعدادات مطلوبة، ويمكن لأي شخص إضافة صفحة.
المشكلة هي أن يتكدس ويكيس الصفحات بسرعة أكبر مما يتم صيانته. وعادة ما تكون مساحة التلاقي لمشروع مدته سنتان صفحاتٍ دقيقة. الصفحات التي عفا عليها الزمن، ولا توجد طريقة موثوقة لتحديد أيّها. البحث عن كل شيء بالتساوي. لا توجد عملية مراجعة. لا أحد يملك أي شيء.
يواجه ويكيس GitHub نفس المشكلة مع قيد إضافي: يعيشون في مستودع منفصل عن التعليمات البرمجية الخاصة بك. طلب سحب يغير واجهة برمجة التطبيقات لا يدعو أي شخص تلقائياً إلى تحديث المستندات. الفجوة بين التعليمات البرمجية والوثائق تتسع بصمت.
الفرق التي تستخدم ويكيس بشكل جيد هي الاستثناء. ولديهما عادة معايير إنفاذ خاصة بكاتب تقني. معظم الفرق لا تفعل ذلك.
المفهوم والأدوات المماثلة: رائع للأفرقة الداخلية، سيئ طول العمر
والمفهوم جيد حقا بالنسبة للوثائق الداخلية - كأدلة للتدوين، والكتب الدفترة، وعمليات الأفرقة، ومذكرات الاجتماعات. المحرر مرن ، الأذونات حبيبة ، وهي سهلة بما فيه الكفاية للمساهمين غير التقنيين في الواقع يستخدمونها.
بالنسبة لوثائق المشروع التي يقصد بها أن تعيش جنبا إلى جنب مع الشفرة، فهي قاصرة بعدة طرق.
المستندات الخاصة بك موجودة في قاعدة بيانات Notion، وليس في المستودع الخاص بك. لا يوجد أي استعراض مختلف، لا يوجد نشر آلي. وإذا غيّر المفهوم تسعيره، فإنه يبطل إحدى السمات، أو يبعد عنها ببساطة، فإن الهجرة تصبح وظيفة يدوية للتصدير وإعادة التشكيل.
المشكلة الأعمق هي إمكانية الاكتشاف. الوثائق التي تعيش في مفهوم ليست مفهرسة بجانب الشفرة الخاصة بك. لن يجد المطور الذي يحمي اسم دالة صفحة المدخل التي تفسر لماذا يعمل بالطريقة التي يعمل بها. النظامان لا يتحدثان مع بعضهما البعض.
مدفوع: صادق ولكن من الصعب قياسه
ويعتمد الكثير من المشاريع الأصغر حجما - والعديد من المشاريع المفتوحة المصدر - اعتمادا يكاد يكون كليا على الشبكة المذكورة. وهناك ملف واحد، حافظ على جودته، ويشمل التركيب، والاستخدام، والمبادئ التوجيهية للمساهمة.
هذا يعمل بشكل مدهش للأدوات المركزة ذات API مستقر. والقيد الذي يفرضه أحد الملفات هو ترتيب الأولويات. لا يوجد أي امتداد وثائقي لأنه لا يوجد مكان يذهب إليه.
وهو ينهار عندما يتجاوز مشروع ما درجة معينة من التعقيد. إعادة توجيه تغطي خمسة عشر خياراً مختلفاً من خيارات التشكيل، وثلاثة أهداف للنشر، ودليل للترحيل من متجر الإصدار 1 إلى v2 يمكن قراءته. في تلك المرحلة فالفرق إما أن تسمح لها بالتهوب أو تبدأ في بناء شيء آخر.
Docs-as co: النمط الذي يقاس
المشاريع ذات التوثيق الجيد باستمرار تميل إلى استخدام نفس النمط الأساسي: ملفات Markdown في المستودع، بناء بواسطة مولد موقع ثابت، يتم نشره جنبا إلى جنب مع كل اصدار.
مستندات كوبرنيتس هي في نفس المونوريبو مثل الكونجرس، التي تم استعراضها في نفس طلب سحب التدفق. كتاب الراست هو مشروع ماركداون على GitHub مع مئات المساهمين. أما وثائق شركة أسترو فهي موقع "أسترو ستارفير" ملتزم به إلى جانب الإطار نفسه.
ما يجعل هذا العمل ليس الأداة إنه سير العمل. الوثائق تعيش بجوار البرمجة، لذلك يتم تحديثها عند تغيير التعليمات البرمجية. ويحتاج أي استعراض رسمي يضيف راية جديدة إلى تحديث المستندات قبل دمجها. وعملية الاستعراض تقوم بإنفاذها.
والاستحقاق الثانوي هو الاستدامة. لا تزال ملفات Markdown من عام 2015 قابلة للقراءة والنشر في عام 2027. ولا يتطلب الأمر أي هجرة، ولا شكل تصدير مملوك، ولا اعتماد على المنصة. المحتوى هو فقط ملفات نصية في مجلد.
التكرير الذي يقتل الوثائق كشفرة للمساهمين غير الفنيين
والضعف الحقيقي الوحيد لنهج "ماركداون في Git" هو أنه يفترض أن الجميع مرتاحون لمحرر نصوص ولطلب سحب. للعديد من الفرق على ما يرام. وبالنسبة للأفرقة التي تضم مساهمين غير تقنيين - التسويق والمنتجات والدعم - يخلق ذلك احتكاكا يؤدي إلى تجاهل المستندات أو صيانتها في نظام مواز.
هذا هو المكان الذي يناسب فيه نظام إدارة المحتوى المدعوم بنظام Git. أدوات مثل LightCMS تجلس أمام المستودع وتعطي المساهمين تجربة محرر حقيقية بينما لا يزال الالتزام بملفات Markdown إلى المستودع. يتناول المحرر التنسيق. ويتولى نظام إدارة المحتوى هذا الالتزام. المساهم لا يرى أبدا محطة طرفية.
النتيجة هي نفسها مثل "docs-as co-code" - المحتوى في "Markdown" ، الذي تم إصداره في Git، نشر بواسطة خط الأنابيب الحالي الخاص بك - ولكن يمكن الوصول إليه للأشخاص الذين لا يريدون استخدام Git مباشرة.
ما يصلح بالفعل في عام 2027
النمط الذي يبقى في الأعلى بسيط: ملفات Markdown في المستودع الخاص بك، بنيت بواسطة مولد موقع ثابت، تم مراجعتها في طلبات السحب ، تم نشرها عند الدمج.
والأدوات المحددة حول هذا النمط لا تؤثر على سير العمل. إذا كان فريقك يستخدم GitHub، يعطيك موقع مصباح أو Docusaurus الملتزم بنفس المستودع كل شيء: البحث، الإصدار، تجربة القراءة السليمة، وعملية المراجعة التي تحافظ على المستندات في تزامن مع الكود.
إذا كان لديك مساهمين غير تقنيين، ضع محرر مدعوم بـ Git-أمامها حتى يتمكنوا من الكتابة دون لمس المحطة الطرفية. ويظل الإعداد الأساسي على حاله. يبقى المحتوى في المستودع الخاص بك.
المشاريع التي تحتوي على أفضل الوثائق ليست تلك التي لديها أفضل أداة. إنهم الذين جعلوا التوثيق جزءا من نفس سير العمل كالتعليمات البرمجية.
الأسئلة الشائعة
ما هو رمز docs-as-code؟
Docs-as code هي ممارسة كتابة الوثائق والمحافظة عليها باستخدام نفس الأدوات وسير العمل كبرنامج تطوير: ملفات نصية بسيطة (عادة Markdown)، التحكم في الإصدار (عادة Git)، مراجعة الرموز، والنشر الآلي. ويحتفظ بالوثائق قريبة من الكود الذي يصفه ويجعل التحديث جزءا من سير العمل العادي للتطور.
هل ماركداون جيد بما فيه الكفاية للتوثيق؟
نعم، بالنسبة للأغلبية الساحقة من المشاريع. يعالج التصنيف العناوين والكتل البرمجية والجداول والصور والروابط. مولدات المواقع الثابتة مثل Starlight، و Docusaurus، و MkDocs تضيف البحث، والملاحة، والإصدار، وتجربة القراءة المناسبة في الأعلى. القيود على النص العادي هي ميزة: يمكن قراءتها في أي محرر، عظيم، قابل للتشتت، ومستديمة عبر عقود.
كيف يساهم الكتّاب غير الفنيين في توثيق Markdown؟
أدوات نظام إدارة المحتوى المدعومة Git-CMS مثل LightCMS توفر محرر غني يُلزم Markdown للمستودع الخاص بك دون أن يطلب من المساهمين استخدام Git مباشرة. يبقى المحتوى في مستودع البيانات الخاص بك في ماركداون عادي. والمحرّر ليس سوى وصلة أيسر منالا لنفس الملفات الأساسية.
ما هو أفضل مولد موقع ثابت للتوثيق؟
يعتمد على المكدس الخاص بك. Astro Starlight و Docusaurus هما أكثر الخيارات تكاملا مع البحث الجيد خارج الصندوق. MkDocs مع المواد ممتاز لمشاريع بايتون. إذا كنت بالفعل على Hugo أو Eleventy في مدونتك، يمكنهم التعامل مع المستندات أيضًا. المولد يهم أقل من الاحتفاظ بالمستندات في نفس المستودع كالتعليمات البرمجية الخاصة بك.