توليد التوثيق من الشيفرة البرمجية: ما يُصيب فيه الذكاء الاصطناعي وما يُخطئ
وجّهوا نموذجًا إلى مستودع شيفرة واطلبوا منه مركز مساعدة، وسيعطيكم واحدًا. سيبدو مكتملًا. ثم تقرؤون المقالة الرابعة فإذا بها تحدّث عملاءكم عن PlanTier.PRO_LEGACY وعن شاشة في المسار /admin/impersonate.
إذن، هل يستطيع الذكاء الاصطناعي توليد التوثيق من الشيفرة؟ نعم، والمسودات مفيدة. فالذكاء الاصطناعي بارع في العثور على كل ميزة، وفي إصابة تسميات الأزرار، وفي إنتاج مسودة أولى متسقة. لكنه، بشكله الخام الخارج من النموذج، يخطئ باستمرار في ثلاثة أمور: يسرّب مصطلحات داخلية، ويوثّق شاشات لا يراها مستخدموكم، ويصف الشيفرة بدل المهمة التي يحاول المستخدم إنجازها. والحل أن تؤسسوا المسودات على التطبيق وهو يعمل، وأن يراجع إنسان كل شيء قبل النشر.
وفيما يلي السبب، وكيف تُعدّون ذلك بحيث تستحق المخرجات الشحن.
نوعان مختلفان جدًا من “التوثيق من الشيفرة”
يقصد الناس أمرين حين يبحثون عن هذا، ومن المفيد الفصل بينهما.
وثائق مرجعية للمطورين. مراجع واجهات البرمجة (API) ووثائق مجموعات التطوير (SDK) وتواقيع الدوال. هذه مشكلة محلولة في معظمها ولا تحتاج إلى الذكاء الاصطناعي أصلًا. فأدوات مثل TypeDoc وSphinx autodoc وJavadoc وأدوات OpenAPI مثل Swagger UI تقرأ شيفرتكم أو مواصفاتكم وتنتج صفحات مرجعية بصورة حتمية. وهي مملة وموثوقة، وهذا ما تريدونه من الوثائق المرجعية.
وثائق المستخدمين. مقالات مركز المساعدة للناس الذين لن يروا شيفرتكم أبدًا: “كيف أصدّر فواتيري”، “كيف أضيف زميلًا”. هذا هو النوع الصعب، وهنا تكون مولّدات التوثيق بالذكاء الاصطناعي مفيدة فعلًا ومحفوفة بالمخاطر فعلًا.
يتناول هذا المقال النوع الثاني. وإذا كنتم تحتاجون إلى ملف README أو تعليقات على الشيفرة، فمساعد البرمجة لديكم يؤدي ذلك أصلًا بما يكفي.
ما يجيده الذكاء الاصطناعي حين يولّد وثائق المستخدمين من الشيفرة
لنُعطِ الفضل لأهله. النموذج الذي يقرأ قاعدة شيفرة أفضل من الإنسان في بضع مهام محددة.
يجد كل شيء
يكتب البشر الوثائق من الذاكرة، والذاكرة تنسى الميزات. استيراد CSV الذي بناه أحدهم قبل ثمانية أشهر. واختصار لوحة المفاتيح. والإعداد الذي لا يظهر إلا في باقة الفريق. أما النموذج الذي يقرأ ملف مساراتكم ومكونات التنقل والنماذج فينتج جردًا كاملًا، وهذا الجرد وحده يستحق التمرين. فلدى معظم مراكز المساعدة ثغرات لا يعرفها أحد.
يصيب التسميات بدقة
نص الزر موجود في الشيفرة: "Export CSV" و"Send invite". سينقله النموذج حرفيًا، بينما يكتب الإنسان “انقروا على زر التصدير” ويترك القارئ يخمّن.
يلاحظ الحدود والقواعد
قواعد التحقق تعيش في الشيفرة. حد أقصى لطول اسم المشروع، وسقف لحجم الملف، وفحص دور يجعل زرًا رماديًا. هذه بالضبط التفاصيل التي تولّد تذاكر الدعم (“لماذا لا أستطيع حفظ هذا؟”) وبالضبط التفاصيل التي لا يعرفها كاتب بشري.
ما يُخطئ فيه الذكاء الاصطناعي حين يولّد التوثيق من الشيفرة
هذا هو الجزء الذي لا تضعه معظم الأدوات على صفحاتها التعريفية. وبحسب تجربتي، تظهر أنماط الفشل هذه في كل مسودة خام تقريبًا من الذكاء الاصطناعي.
1. تتسرب المصطلحات الداخلية
تستخدم شيفرتكم وواجهتكم كلمات مختلفة. الجدول اسمه workspaces والواجهة تقول “Team”. والتعداد هو PlanTier.PRO_LEGACY وصفحة الأسعار تقول “Pro”. وظلت الميزة تُسمى smartRouting داخليًا لعام كامل قبل أن يسميها التسويق “Auto-assign”.
والنموذج يقرأ الشيفرة، فيستخدم كلمات الشيفرة. فتحصلون على جمل مثل “أنشئوا مساحة عمل (workspace) جديدة (org) من صفحة Teams”، وهي محيّرة للعملاء وخاطئة أيضًا. والأسوأ أنها تسرّب أسماء لم تقصدوا أن تكون علنية.
2. يوثّق شاشات لا يراها مستخدموكم
يرى النموذج مسارًا فيكتب له مقالة. ولا يعلم أن:
/admin/*هي أدوات الدعم الداخلية لديكم- صفحة “الاستيراد الجماعي” خلف علم ميزة (feature flag) مفعّل لثلاثة حسابات تجريبية
- إعدادات “Teams” لا تظهر إلا في باقة Business
- تدفق الاستقبال القديم شيفرة ميتة لم يزلها أحد
فيكتب مقالات مساعدة لكل هذا. وفي أحسن الأحوال يبحث العملاء عن شاشات غير موجودة لهم ويراسلونكم. وفي أسوأ الأحوال تكونون قد نشرتم خارطة طريقكم، أو دليلًا لأداة انتحال الهوية الإدارية لديكم.
3. يصف الشيفرة بدل مهمة المستخدم
هذا هو الخطأ الدقيق، وهو الأكثر شيوعًا. يشرح النموذج ما تفعله الشيفرة، لأنها ما ينظر إليه. أما المستخدمون فلا يهمهم ما تفعله الشيفرة. إنهم يريدون إنجاز شيء.
النسخة اليسرى دقيقة. لكنها عديمة الفائدة لمن طلب منه محاسبه للتو فواتير الربع الماضي. أما النسخة اليمنى فتبدأ من الهدف وتستخدم الكلمات التي على الشاشة وتبيّن أين تنقرون. ويرسم إطار Diátaxis هذا الخط جيدًا: دليل الإرشاد (how-to) يخدم هدفًا، والمرجع يصف الآلية. والمسودات الخام من الذكاء الاصطناعي تنجرف نحو المرجع حتى حين تطلبون دليل إرشاد.
4. يخمّن بثقة سلوكًا لا تحسمه الشيفرة
كثير مما يختبره المستخدمون لا تقرره الشيفرة وحدها. فإرسال رسالة التأكيد فعلًا يعتمد على الإعدادات. وشكل الصفحة يعتمد على البيانات فيها. وسياسة الاسترداد وساعات الدعم وما يحدث للبيانات بعد الإلغاء ليست عادةً في المستودع أصلًا.
ويملأ النموذج هذه الفجوات بتخمينات معقولة مكتوبة بالنبرة الواثقة نفسها التي كُتب بها كل شيء آخر. وهذا هو الجزء الخطر: الجمل الخاطئة لا تبدو مختلفة عن الصحيحة.
لماذا يهم تأسيس الوثائق على التطبيق وهو يعمل
الشيفرة تخبركم بما يمكن أن يوجد. أما التطبيق العامل فيُظهر ما يراه المستخدم فعلًا.
إذا ولّدتم التوثيق من الشيفرة وحدها، فأنتم توثّقون نظرية عن منتجكم. شغّلوا التطبيق، وسجّلوا الدخول كمستخدم عادي على باقة عادية، فيتقلص معظم المشكلات أعلاه:
- الشاشات الإدارية والمحجوبة بأعلام الميزات لا تظهر ببساطة، فلا تُوثَّق.
- التسميات في لقطة الشاشة هي التسميات التي يراها العملاء، وهذا يكشف المصطلحات الداخلية.
- إذا كانت المقالة تقول “انقروا على Export CSV” ولقطة الشاشة لا تحتوي على زر تصدير، فقد اكتشفتم خطأ (في الوثائق أو في المنتج) قبل أن يكتشفه عميل.
يمكنكم فعل ذلك بأنفسكم بأداة أتمتة المتصفح. ونص Playwright بسيط يسجّل الدخول كمستخدم تجريبي ويلتقط صفحة لمقالة يبدو هكذا:
// docs/capture/billing.spec.ts
import { test } from '@playwright/test';
test('capture billing page for the invoices article', async ({ page }) => {
await page.goto('http://localhost:3000/login');
await page.getByLabel('Email').fill('docs-demo@example.com');
await page.getByLabel('Password').fill(process.env.DOCS_DEMO_PASSWORD!);
await page.getByRole('button', { name: 'Sign in' }).click();
await page.goto('http://localhost:3000/settings/billing');
await page.screenshot({ path: 'docs/img/download-invoices-step-1.png' });
});
تغطي وثائق لقطات الشاشة في Playwright اللقطات الخاصة بعنصر واحد ولقطات الصفحة الكاملة. والجزء الصعب ليس النص البرمجي، بل وجود بيانات تجريبية مهيأة تبدو حقيقية وتسجيل دخول يعمل في CI. ونستعرض الإعداد كاملًا في كيف تنشئون لقطات شاشة للمنتج تلقائيًا.
لماذا تظل المراجعة البشرية غير اختيارية
حتى مع تأسيس جيد، لا بد أن يقرأ شخص يعرف المنتج كل مقالة قبل نشرها. لا أن يتصفحها بسرعة. بل أن يقرأها.
وهذه قائمة التحقق التي أعطيها للمراجع:
- الكلمات تطابق الواجهة. كل اسم ميزة وزر وعنصر قائمة هو ما يراه العملاء، لا ما يسميه المهندسون.
- كل شاشة يمكن الوصول إليها. العميل على الباقة التي تستهدفها المقالة يستطيع فعلًا الوصول إليها. والميزات الخاصة ببعض الباقات تذكر ذلك.
- تبدأ من المهمة. العنوان شيء يكتبه المستخدم في خانة البحث. والخطوة الأولى نقرة، لا فقرة من السياق.
- السياسات حقيقية. أي شيء عن المال أو البيانات أو الإلغاء أو ساعات الدعم يأتي منكم، لا من النموذج.
- لا شيء غير مُصدَر. لا ميزات تجريبية ولا أدوات داخلية ولا أسماء لم يعلنها التسويق.
ومراجعة مسودة معقولة أسرع بكثير من الكتابة من صفحة بيضاء، وهذا هو المقصود كله. لكنها الخطوة التي تحوّل مسودة معقولة إلى توثيق يمكنكم الوقوف خلفه. وإذا تخطيتموها، فأنتم تنشرون تخمينات النموذج باسم شركتكم.
سير عمل ذاتي يمكنكم تنفيذه مع مساعد البرمجة
لستم بحاجة إلى مولّد توثيق مخصص بالذكاء الاصطناعي لتحصلوا على معظم الفائدة. مع Cursor أو Claude Code أو Copilot أو أدوات مشابهة:
1. اطلبوا جردًا لا مقالات. شيئًا مثل:
List every user-facing feature in this app. For each one give:
- the route or screen where a user finds it
- the exact button/menu labels involved
- any plan, role or feature-flag check guarding it
Do not write documentation yet.
2. قلّموه بأيديكم. اشطبوا المسارات الإدارية والأدوات الداخلية والميزات التجريبية المحجوبة والشيفرة الميتة. يستغرق هذا عشر دقائق ويمنع أسوأ الإخفاقات.
3. أعطوه مسردًا. قائمة قصيرة تربط مصطلحات الشيفرة بمصطلحات الواجهة (workspace → Team وPRO_LEGACY → Pro). الصقوها في كل تعليمة صياغة.
4. صياغة مهمة واحدة لكل مقالة. اطلبوا دليل إرشاد مكتوبًا لمستخدم غير تقني، يستخدم فقط تسميات من الجرد، ويبدأ بالهدف، ويضع علامة [CHECK] على أي جملة لا يتأكد منها.
5. تجولوا في التطبيق والتقطوا لقطات الشاشة. اتبعوا كل مقالة بأنفسكم. صححوا الخطأ وأضيفوا لقطات الشاشة.
6. راجعوا بحسب القائمة أعلاه، ثم انشروا. من حيث البنية، فإن كيف تكتبون مقالات مركز مساعدة يستخدمها الناس فعلًا يتضمن قالبًا يناسب هذا الموضع جيدًا.
وضعف المسار الذاتي في الخطوة 7، وهي غير موجودة بعد: ملاحظة أن تغيير الشيفرة الأسبوع القادم يجعل المقالة الثانية عشرة خاطئة. وهذه مشكلة منفصلة، نتناولها في كيف تحافظون على تحديث التوثيق.
كيف يتعامل Ellie Docs مع هذا
بنينا Ellie Docs حول أنماط الفشل أعلاه، وهذا هو كيف ينسجم معها.
يقرأ مستودعكم ويرسم خريطة للميزات والشاشات الموجهة للمستخدم، ثم يصوغ مركز مساعدة منظمًا بحسب ما يفعله المستخدمون.

ويشغّل تطبيقكم في بيئة معزولة (sandbox) ويلتقط لقطات شاشة حقيقية للمنتج بعد تسجيل الدخول، ويضعها في المقالات. وتبيّن كل مقالة الميزات التي تستند إليها، فحين تتغير هذه الميزات في الشيفرة، تعرف Ellie أن المقالة قد تتأثر.

وعند كل طلب سحب (PR) يُدمج، يفحص المقالات التي يمسها التغيير ويقترح تعديلات على هيئة فروقات (diff) تقبلونها أو ترفضونها. وحين يكتب سجل التغييرات (changelog) من طلبات السحب المدمجة، يحجب المدخلات الخاصة بالأعمال غير المُصدَرة أو المحجوبة بأعلام الميزات. لا شيء يُنشر من تلقاء نفسه. أنتم من تنشرون.

وما زال يخطئ أحيانًا. فهو لا يستطيع معرفة سياساتكم، وسيختار أحيانًا كلمة من الشيفرة بدل كلمة من الواجهة. ولهذا يمر كل مسودة وكل اقتراح عليكم. وإذا كنتم تعملون على تطبيق بُني بمنشئ تطبيقات بالذكاء الاصطناعي، فإن دليل توثيق تطبيق مبني بأسلوب vibe coding يغطي التعقيدات الإضافية هناك.
بعض الأسئلة التي يطرحها الناس
هل هناك مولّد توثيق مجاني بالذكاء الاصطناعي؟ مساعد البرمجة لديكم مع سير العمل الذاتي أعلاه لا يكلف شيئًا إضافيًا. ولدى Ellie Docs أيضًا باقة مجانية لا تتطلب بطاقة، إذا فضلتم أن تُعالج لقطات الشاشة وتتبع التحديثات عنكم.
هل يستطيع الذكاء الاصطناعي توليد وثائق API دون مواصفات OpenAPI؟ يستطيع، بقراءة معالجات المسارات لديكم. وإذا كانت لديكم مواصفات بالفعل، فاستخدموا الأدوات القياسية مثل Swagger UI أو Redoc؛ فهي حتمية ومجانية. ويولّد Ellie Docs مرجع API من الشيفرة دون مواصفات في باقة Growth، وهذا يفيد إن لم تكتبوا مواصفات يومًا.
هل أدع الذكاء الاصطناعي ينشر التوثيق تلقائيًا؟ لا. دعوه يصوغ ويقترح. وينبغي أن يوافق شخص يعرف المنتج على كل ما سيقرؤه العملاء، خصوصًا ما يتعلق بالفوترة أو البيانات.
هل ستكون الوثائق المكتوبة بالذكاء الاصطناعي دقيقة؟ بقدر دقة التأسيس والمراجعة وراءها. من الشيفرة وحدها، توقعوا مسودة مفيدة فيها أخطاء واثقة. أما إذا أُسّست على التطبيق العامل وراجعها شخص يعرف المنتج، فيمكن أن تكون أفضل مما تكتبه معظم الفرق يدويًا، لأنها تغطي ميزات نسيها البشر في الغالب.
إذا أردتم مسودات مؤسسة على تطبيقكم الحقيقي، مع لقطات شاشة واقتراحات لكل طلب سحب توافقون عليها، فـجرّبوا Ellie Docs مجانًا. اربطوا مستودعًا وراجعوا أول مركز مساعدة مصوغ اليوم.