كيفية التحديث التلقائي للوثائق مع كل إصدار

تم التحديث في 3 نوفمبر 2026

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

يستعرض هذا الدليل خط الأنابيب هذا مع أي أداة أولاً (GitHub Actions، GitLab، Bitbucket، صفحة سجل التغييرات)، ثم يوضح كيف يقوم Autopilot من Clevera بتشغيل نفس الحلقة لمركز مساعدة يحتوي على مقاطع فيديو.

ما هي الوثائق المستمرة؟#

تعرّف Swimm، التي نشرت هذا المصطلح، الوثائق المستمرة بأنها إنشاء وتحديث الوثائق بشكل تدريجي كجزء من سير عمل التطوير، بدلاً من مشاريع اللحاق بالركب العرضية. معظم الأدوات المبنية على هذه الفكرة، والتي تُباع الآن غالباً باسم "الوثائق ذاتية التحديث"، تراقب الالتزامات (commits) أو طلبات السحب (pull requests) وتحدث وثائق المطورين بجانب الكود.

تحتاج مراكز المساعدة الموجهة للعملاء إلى مشغل مختلف. القراء لا يرون التزاماً (commit)؛ بل يرون إصداراً. يوضح الجدول المقايضات.

الحجة للأتمتة هي السرعة. وجدت أبحاث DORA لعام 2021 حول حالة DevOps أن الفرق النخبوية تنشر 973 مرة أكثر من الفرق ذات الأداء المنخفض. لا يغير كل نشر ما يراه القراء، لكن الفرق تشحن بوتيرة أكبر بكثير مما يمكن لأي شخص إعادة فحص المقالات يدوياً. وجدت نفس الأبحاث أن الفرق ذات الوثائق عالية الجودة كانت أكثر عرضة بـ 3.8 مرة لتنفيذ أفضل ممارسات الأمان، لذا فإن الوثائق ليست قضية ثانوية. والوثائق القديمة شائعة: في استطلاع GitHub للمصادر المفتوحة لعام 2017، واجه 93% من المشاركين وثائق غير مكتملة أو قديمة، وقال 60% من المساهمين إنهم نادراً ما يساهمون في الوثائق أو لا يفعلون ذلك أبداً.

الخطوة 1: اكتب ملاحظات إصدار يمكن لمهمة التوثيق استخدامها#

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

• جمّع التغييرات حسب النوع. يستخدم Keep a Changelog تصنيفات: المضاف (Added)، والمغير (Changed)، والمهمل (Deprecated)، والمحذوف (Removed)، والمصلح (Fixed)، والأمني (Security). "المضاف" يعني عادةً مقالاً أو فيديو جديداً؛ بينما يعني "المغير" و"المحذوف" أن المحتوى الحالي أصبح خاطئاً.
• افصل ما يراه المستخدمون عما لا يرونه. تقوم ملاحظات الإصدار التي يتم إنشاؤها تلقائياً في GitHub بفرز طلبات السحب المدمجة حسب التصنيف في .github/release.yml، ويمكنها استبعاد التصنيفات تماماً.

# .github/release.yml
changelog:
  exclude:
    labels: [internal, chore]
  categories:
    - title: New
      labels: [feature]
    - title: Changed in the app
      labels: [ui-change]
    - title: Fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]

يعد تصنيف "ui-change" التصنيف الأكثر فائدة للإضافة: فهو يخبر مهمة التوثيق بالعناصر التي يمكن أن تفسد المقال. قم بتسمية الشاشة في عنوان طلب السحب أيضاً ("إعدادات الفوترة: نقل التذكيرات إلى الأتمتة")، حتى يمكن مطابقة التغيير مع الصفحات التي تعرض تلك الشاشة.

الخطوة 2: التحديث التلقائي للوثائق عند الإصدار: ابدأ مهمة#

يمكن لكل مضيف Git رئيسي بدء مهمة عند الشحن، وهي الطريقة التي تولد بها تحديثات الوثائق من إصدارات GitHub أو ما يعادلها في GitLab وBitbucket. تختلف التفاصيل.

في GitHub، يبدو سير العمل الأدنى كما يلي:

# .github/workflows/docs-on-release.yml
name: Docs on release
on:
  release:
    types: [published]
permissions:
  contents: read
jobs:
  draft-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: Draft docs updates for this release
        env:
          TAG: ${{ github.event.release.tag_name }}
          NOTES: ${{ github.event.release.body }}
        run: ./scripts/draft-docs-updates.sh

استخدم published بدلاً من created: وفقاً لـ مرجع الأحداث الخاص بـ GitHub، فإن created لا يعمل مع مسودات الإصدارات، بينما يغطي published كلاً من الإصدارات المستقرة وإصدارات ما قبل الإطلاق. مرر ملاحظات الإصدار عبر متغير بيئة كما هو موضح أعلاه، وليس مباشرة في أمر shell، لأن نص الإصدار هو إدخال مستخدم. وإذا كانت أداة مثل release-please أو semantic-release تنشئ إصداراتك باستخدام الرمز الافتراضي، فإن الأحداث التي تطلقها لن تبدأ سير عمل التوثيق الخاص بك؛ امنح تلك الأداة رمز تطبيق GitHub أو رمز وصول شخصي بدلاً من ذلك.

في GitLab وBitbucket، المكافئ هو مهمة تعمل على الوسوم:

# .gitlab-ci.yml
draft-docs:
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - ./scripts/draft-docs-updates.sh "$CI_COMMIT_TAG"

# bitbucket-pipelines.yml
pipelines:
  tags:
    'v*':
      - step:
          script:
            - ./scripts/draft-docs-updates.sh "$BITBUCKET_TAG"

الخطوة 3: اعثر على الصفحات ومقاطع الفيديو التي يؤثر عليها كل إصدار#

هذه هي الخطوة التي تتخطاها معظم الأدلة، وهي التي تقرر ما إذا كانت الأتمتة مفيدة. تقول ملاحظة الإصدار "تم نقل التذكيرات إلى الفوترة ← الأتمتة"؛ يجب أن تحول مهمتك ذلك إلى "هذه المقالات الثلاث ومقطعي الفيديو أصبحوا الآن خاطئين".

ثلاث طرق، من الأبسط إلى الأقوى:

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

يمكن أن يكون المطالبة (prompt) لهذا الحكم قصيراً:

You check help articles against a software release.
Release notes: {release_notes}
Article ({url}): {article_text}

Answer in JSON: {"verdict": "still_right" | "text_fix" | "new_screenshots_or_footage",
"reason": "<one sentence quoting the release item>",
"changed_steps": [<step numbers>]}
Only use facts from the release notes. If unsure, answer "text_fix" and say why.

الخطوة 4: صُغ التحديثات#

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

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

الخطوة 5: ضع شخصاً بين المسودة والقارئ#

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

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

أي إعداد يناسب فريقك؟#

إذا كان فريقك يعمل بالفعل في Claude Code، يمكنك أيضاً أن تطلب منه تحديث المستندات بعد الإصدار عبر MCP؛ نستعرض ذلك في كيفية تحديث المستندات باستخدام Claude Code بعد كل إصدار.

كيفية التحديث التلقائي للمستندات عند الإصدار باستخدام Clevera Autopilot#

Clevera هي منصة ذكاء اصطناعي تحول تسجيل الشاشة إلى فيديو تعليمي مع تعليق صوتي، ومقال مساعدة خطوة بخطوة، وصفحة في مركز المساعدة المستضاف الخاص بك، بـ 74 لغة. ميزة Autopilot الخاصة بها، والمتاحة في خطتي Pro وCustom، تنفذ الخطوات من 2 إلى 5 أعلاه لمركز مساعدة Clevera.

• المشغل. تقوم وصفة إبقاء مركز المساعدة محدثاً عند الشحن بمراقبة إصدارات المستودع أو التغييرات المدمجة، أو صفحة سجل التغييرات التي تُقرأ يومياً أو أسبوعياً. يتصل GitHub عبر تطبيق للقراءة فقط؛ وتتصل GitLab (gitlab.com) وBitbucket Cloud بنفس الطريقة حيثما توفرت. تتحقق Clevera من المستودع مرة كل ساعة تقريباً. وهي تقرأ ملاحظات الإصدار، والوسوم، وعناوين وأوصاف طلبات السحب، ولا تقرأ الكود الخاص بك أبداً.
• المطابقة. يتحقق كل تشغيل من ما يصل إلى 40 فيديو ومقالاً في مركز المساعدة ويقرأ كل واحد متأثر بالكامل.
• الصياغة. يحصل كل عنصر على حكم: لا يزال صحيحاً، أو إصلاح نصي يظهر قبل وبعد، أو إعادة التسجيل بالخطوات الجديدة. تتطلب إعادة التسجيل استخدام تطبيقي: عنوان تطبيقك، وإذا كان يحتاج إلى تسجيل دخول (حساب تجريبي يعمل بشكل أفضل). يحل الفيديو الجديد محل القديم في نفس الرابط، لذا، كما هو الحال مع تعديلات LiveSync، تظهر التضمينات وصفحات مركز المساعدة الفيديو الجديد دون روابط جديدة.
• المراجعة. ينتظر كل تشغيل موافقتك. يمكنك إلغاء تحديد ما لا تريده والنقر على تشغيل، أو النقر على طلب تغييرات للحصول على خطة جديدة. تنتهي صلاحية الخطة بعد سبعة أيام، ويلتقط التشغيل التالي كل ما حدث منذ ذلك الحين.

المراقبة والتخطيط مجانيان؛ يظهر كل سطر في الخطة رصيده، ويكلف التشغيل العادي من 10 إلى 150 رصيداً. تتوفر نفس الحلقة للفيديوهات بدون مركز مساعدة من خلال تحديث فيديوهاتي عند تغير المنتج، وتقترح تسجيل فيديو لكل ميزة جديدة طريقة تعليمية جديدة لما يضيفه كل إصدار (انظر كيفية عمل فيديو لملاحظات الإصدار للنسخة اليدوية).

حيث لا تعد Clevera الأداة المناسبة: فهي لا تولد مرجع API من الكود أو تكتب CHANGELOG.md الخاص بك. لهذا الجانب، راجع مقارنتنا لـ مولدات سجل التغييرات بالذكاء الاصطناعي، أو خوادم MCP للمستندات إذا كنت تريد وكيل ذكاء اصطناعي لتعديل المستندات في منصة أخرى.

ابدأ مجاناً لبناء مركز المساعدة والفيديوهات أولاً؛ يأتي Autopilot مع خطة Pro. خطوات الإعداد موجودة في مقال المساعدة ربط GitHub أو مستودع آخر بـ Autopilot.

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

هل يمكن للمستندات تحديث نفسها تلقائياً عند الإصدار؟#

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

هل يجب تحديث المستندات عند كل التزام (commit) أم عند كل إصدار؟#

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

كيف أقوم بتشغيل إجراء GitHub (GitHub Action) عند نشر إصدار؟#

استخدم on: release مع types: [published]. إذا تم إنشاء الإصدار بواسطة سير عمل آخر باستخدام GITHUB_TOKEN الافتراضي، فلن يبدأ سير العمل الخاص بك؛ استخدم رمز تطبيق GitHub أو رمز وصول شخصي لأداة الإصدار.

ماذا لو لم ننشر الإصدارات على GitHub؟#

استخدم الإشارة المتاحة لديك: أحداث إصدار GitLab، أو خطوط أنابيب وسوم Bitbucket، أو وظيفة مجدولة تقرأ صفحة سجل التغييرات العامة أو خلاصة RSS الخاصة بها. يمكن لـ Autopilot من Clevera مراقبة صفحة سجل التغييرات يومياً أو أسبوعياً لهذه الحالة تحديداً.

هل يمكن تحديث لقطات الشاشة والفيديوهات تلقائياً أيضاً؟#

يمكن التقاط لقطات الشاشة في اختبارات واجهة المستخدم عند كل بناء. تحتاج الفيديوهات إلى إعادة تسجيل المسار المتغير؛ يمكن لمسجل الذكاء الاصطناعي إعادة تشغيل تعليمات محفوظة مقابل واجهة المستخدم الجديدة، ويمكن لـ Autopilot القيام بذلك لفيديوهات Clevera عندما تزوده بعنوان تطبيقك (وتسجيل دخول إذا كان تطبيقك يحتاجه). شاهد النسخة الجديدة قبل الموافقة عليها.