أفضل ممارسات ضبط إصدار الوثائق

كيف تعمل

1. جمّد نظام الترقيم بمجرد أن تعتمد عليه وثائق حقيقية

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

2. ضع الإصدار والتاريخ والمعتمِد في مكان ثابت واحد على كل قالب

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

3. امنح الإصدار «الحالي» اصطلاح قفل أو تسجيل خروج

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

4. دوّن قاعدة الرئيسي مقابل الفرعي قبل أن تحتاجها أول وثيقة

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

5. سجّل كل مراجعة دورية، بما فيها التي لا تغيّر شيئاً

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

6. دع نسخة حية معتمَدة واحدة تزيل مشكلة القفل كلياً

   افتح الوثيقة كمخطط QueryChart بدل مجموعة ملفات مُتبادَلة بالبريد، فلا يوجد سوى إصدار حالي واحد للتحرير: يُلتقط كل حفظ كقيد جديد في سجل التغييرات تلقائياً، فلا يبقى لاصطلاح تسجيل الخروج شيء يفرضه. راجع /features/version-control.

الأسئلة الشائعة

ما أكبر خطأ واحد في ضبط إصدار الوثائق ينبغي تجنّبه؟

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

كيف أوقف شخصين عن تحرير الإصدار «الحالي» نفسه في آن واحد؟

إما أضف اصطلاح تسجيل خروج صريح (علامة في السجل تُظهر من يفتح الوثيقة، كي يعرف معِدّ ثانٍ أن ينتظر) أو أزل الاحتمال هيكلياً بالاحتفاظ بنسخة حية معتمَدة واحدة بالضبط بدل ملفات مُتبادَلة بالبريد أو قرص مشترك. يفعل QueryChart الثاني: كل وثيقة مخطط حي واحد، ويُرقِّم كل حفظ تلقائياً، ولا توجد نسخة ثانية لتتفرّع. راجع /features/version-control.

ما الذي ينبغي أن يُحسب إصداراً رئيسياً مقابل فرعياً؟

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

هل أحتاج تسجيل مراجعة دورية لم تجد تغييرات مطلوبة؟

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