التوثيق متعدد الإصدارات: صمم دورة الإصدار قبل بنية الروابط

التوثيق متعدد الإصدارات سياسة إصدار تظهر في المحتوى والروابط والاسترجاع. إضافة /v2/ لا تحدد الإصدار المستقر، ولا مدة دعم الصفحات القديمة، ولا تمنع البحث من خلط تعليمات غير متوافقة.

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

اختر سلطة الإصدار

النماذج الشائعة:

• فرع: لكل خط منتج مدعوم فرع توثيق؛
• مسار: corpus واحد يضم /v1/ و/v2/؛
• نطاق: كل إصدار على hostname مستقل؛
• لقطة: سجل نشر يجمد المحتوى بينما يستمر التحرير في المسودة.

يسهل الفرع ربط التوثيق بالشيفرة لكنه يزيد backports. المسار سهل الاكتشاف ويحتاج مرشحات صارمة. النطاق يعزل النشر ويضاعف حوكمة TLS وcanonical. اللقطة تثبت ما يقرأه الجمهور وتحتاج قواعد ترقية واحتفاظ. يمكن الجمع، لكن يجب تسمية سلطة واحدة لكل إصدار عام.

عرّف latest وstable وbeta وEOL

التسمية	المعنى المطلوب إثباته
Latest	أحدث توثيق منشور، وقد لا يكون الموصى به
Stable	الافتراضي المدعوم للمستخدم العادي
Beta	سلوك قابل للتغيير لجمهور محدد
EOL	إصدار انتهى دعمه مع تاريخ وهدف ترحيل

لا تحرك alias stable بصمت. اعرض نسخة المنتج ومراجعة التوثيق وتاريخ النشر وحالة الدعم. لا ينبغي لصفحة beta أن تتصدر إرشاد stable لاستعلام غير مقيد.

قرر فهرسة الإصدارات القديمة

قد يحتاج مستخدمو إصدار مدعوم إلى الصفحات القديمة، لكنها قد ترسل مستخدماً جديداً إلى أوامر منتهية. اختر لكل إصدار: index أو noindex أو تحويل أو حذف وفق سياسة مؤرخة.

افهرس إصداراً قديماً مدعوماً عندما يملك طلباً مستقلاً وتسميته دقيقة. استخدم noindex إذا بقي للرابط المباشر ولا ينبغي أن ينافس. لا تحول إلا إلى محتوى مكافئ؛ API محذوف لا يصبح مكافئاً لصفحة latest.

اجعل canonical ذاتياً للمحتوى المختلف فعلاً. الإشارة من كل القديم إلى latest تصف اختلافات حقيقية كنسخ مكررة.

اجعل التنقل واعياً بالإصدار

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

يجب أن تبقى الروابط الداخلية داخل الإصدار أو تعلن الانتقال. تحقق من الروابط بعد كل إصدار؛ قد يقفز رابط نسبي من /v1/ إلى latest.

قيّد البحث واسترجاع AI

يحتاج كل record أو chunk إلى project وdeployment أو snapshot واللغة والإصدار والvisibility والمسار الأساسي. طبق المرشحات قبل الترتيب أو model call. قارئ v1 لا يجب أن يتلقى parameter خاصاً بـv2.

يجب أن تستشهد الإجابة بالإصدار نفسه. ضع النسخة في اسم citation وURL. احتفظ ببحث حتمي كتراجع، واختبر كلمات مشتركة عبر stable وbeta وEOL.

وازن OpenAPI والأمثلة وسجل التغيير

يجب أن يحدد مرجع API نسخة OpenAPI وservers. اتسق بين الأمثلة وTry it والسجل والنص. لا تعرض schema حديثاً على prose قديم. تحقق من $ref وserver URL لكل نسخة، واربط breaking change بآخر صفحة قديمة صحيحة وأول صفحة جديدة.

احفظ استقرار الاستشهاد والرابط العميق

قد تشير مقالة أو تذكرة أو إجابة AI إلى heading. لا تغير anchors المستقرة من أجل تحرير بسيط. عند النقل، حوّل المسار والfragment إن أمكن، واحتفظ بroute manifest يعطي كل رابط عام سابق نتيجة صريحة.

احفظ تكافؤ اللغات لكل إصدار

يربط hreflang الصفحات المكافئة داخل الإصدار نفسه. لا تربط العربية v1 بالإنجليزية v2 لتعويض غياب ترجمة. لا تعرض fallback إنجليزياً مع بقاء URL عربي.

أنشئ matrix: الإصدار × اللغة × الصفحة، وقارن العنوان والوصف والأقسام والأمثلة والتحذيرات والتاريخ وحالة الدعم. تحتاج الترجمة القديمة إلى workflow ظاهر، وقد تستدعي إزالتها من alternates أو noindex حتى التصحيح.

اختبر رسم الإصدار

لكل إصدار ولغة:

1. اجلب HTML وMarkdown بلا جلسة.
2. تحقق من self-canonical وhreflang المتبادل.
3. أثبت النسخة في الصفحة ومخرجات الآلة.
4. ابحث عن مصطلح خاص وارفض نتائج النسخ الأخرى.
5. افتح citations والأمثلة.
6. افحص روابط قديمة وتحذير EOL.
7. قارن sitemap وllms وroute manifest.

سجل الفجوة كمجهول، لا كاستخدام صفر. الجاهزية تعني رسماً متسقاً، لا homepage جديدة سليمة فقط.

تطبيق الدورة على Nibleaf

ينشر Nibleaf لقطات غير قابلة للتغيير ويفصل versions عن أشجار اللغات. يجب أن تقيد نسخة الإنتاج التنقل والبحث وMarkdown وsitemap وllms وOpenAPI والاستشهادات بهوية snapshot/version نفسها. سلوك المصدر لا يثبت ما يوجد في صورة الإصدار العامة.

رُوجعت المراجع في 2026-09-03: Google والروابط المكررة، Google والنسخ المحلية، Semantic Versioning، وOpenAPI.