مولّد توثيق برمجيات بالذكاء الاصطناعي

سجّل سير عمل للبرنامج وحوّله إلى توثيق خطوة بخطوة مع لقطات شاشة. يلتقط Trupeer سير العمل، وينشئ الدليل مع لقطة شاشة لكل خطوة، ويقدّم فريقك مسودة للمراجعة والنشر والتحديث عند تغيّر الواجهة.

هذا مخصّص لتوثيق كيفية استخدام البرامج، وليس لإنشاء مرجع API أو مواصفات المطورين.

لماذا يختلف توثيق البرامج

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

• الخطوات هي إجراءات واجهة: ماذا تنقر، وأين، وبأي ترتيب—وهو أمر متعب للكتابة وسهل أن يُخطئ فيه الشخص بشكل غير ملحوظ من الذاكرة

• يجب أن تتطابق لقطات الشاشة مع الخطوة: لقطة شاشة لحالة غير صحيحة أسوأ من عدم وجود لقطة، والتقاطها بشكل منفصل هو أبطأ جزء في كتابة توثيق البرامج

• الواجهة تستمر بالتغيّر: إعادة التصميم تُبطل الصياغة وكل لقطة شاشة مرة واحدة، لذلك قد يصبح توثيق البرامج قديمًا بسرعة لأن الواجهات تتغير كثيرًا

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

كيف يعمل مُولّد توثيق البرامج بالذكاء الاصطناعي

ثلاث خطوات من استخدام البرنامج إلى توثيق منشور.

الخطوة 1: سجّل سير العمل أو ارفعه

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

الخطوة 2: أنشئ دليل البرنامج

يحدد Trupeer إجراءات الواجهة، ويلتقط لقطة شاشة لكل خطوة، ويُنشئ مسودة نص التعليمات، ثم ينتج فيديو مُسردًا من نفس التسجيل.

الخطوة 3: عدّل وانشر وحدّث

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

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

لماذا تستخدم مُولّد توثيق البرامج بالذكاء الاصطناعي؟

لأن معظم الجهد في توثيق البرامج لا يكون في الكتابة. بل في إعادة بناء سير العمل من الذاكرة والتقاط لقطات الشاشة يدويًا، وكلا الأمرين يتكرر كل مرة تتغير فيها الواجهة. هذا هو العمل الذي يزيله المُولّد.

ما الذي يمكنك إنشاؤه باستخدام Trupeer

• أدلة البرامج: تعليمات خطوة بخطوة لميزة أو سير عمل، مع لقطة شاشة لكل خطوة

• لقطات الشاشة: يتم التقاطها من سير العمل، ثم يمكن قصّها وإضافة تعليقات عليها وطمس البيانات الحساسة فيها

• أدلة المنتجات الموجهة للعملاء: يتم نشرها في قاعدة المعرفة أو مشاركتها عبر رابط

• جولات الفيديو التوضيحية: فيديو مُسرد، من نفس التسجيل، كمخرَج ثانوي إلى جانب الدليل المكتوب

• توثيق العمليات الداخلية: نفس سير العمل مكتوبًا للفريق بدلًا من العميل

• الإصدارات المترجمة: يتم نشرها بلغات أخرى من مصدر واحد

• التصديرات: PDF أو Word عندما يلزم ملف

بالنسبة لمرجع API وأدلة SDK ومواصفات المطورين، فهذا تصنيف مختلف. راجع أدوات الذكاء الاصطناعي للتوثيق التقني.

ما الذي يجعل التسجيل جيدًا لتوثيق البرامج

الدليل المُولّد لا يكون أفضل من جودة الالتقاط. هناك أشياء قليلة تحدد ذلك، ولا يتطلب أي منها وقتًا إضافيًا بمجرد أن تعرفها.

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

• ابدأ من شاشة يمكن التنبؤ بها:
  ابدأ من عنوان URL أو اعرض ما يمكن للقارئ الوصول إليه أيضًا، وليس من منتصف جلسة مع تطبيق الفلاتر مسبقًا

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

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

• احتفظ بسير عمل واحد لكل تسجيل:
  وضع ميزتين في تسجيل واحد ينتج دليلًا مربكًا، وتقسيمه لاحقًا يكلف أكثر من تسجيل مرتين

• اضبط النافذة على حجم قياسي:
  الأبعاد المتسقة عبر التسجيلات تعني لقطات شاشة متسقة عبر مكتبتك

ماذا تضيف بعد الالتقاط

يُظهر التسجيل ما تم فعله. لا يُظهر ما يحتاج القارئ إلى معرفته، وبالنسبة لتوثيق البرامج تكون الفجوات متسقة بما يكفي للتحقق منها مباشرة.

• المتطلبات المسبقة: الصلاحية أو الدور أو الخطة المطلوبة قبل الخطوة الأولى. اكتشاف أنك تفتقد الوصول في الخطوة السابعة هو السبب الأكثر شيوعًا وراء التخلي عن الدليل

• ماذا يفعل الإعداد فعليًا: يُظهر التسجيل تبديل خيار قيد التشغيل/الإيقاف، وليس ما الذي يتغير عند تبديله

• الحدود والقيود: أحجام الملفات، وحدود الأحرف، وحدود المعدل، وقيود الخطة التي لا تظهر إلا عند الوصول إليها

• ما الذي يحدث بعد ذلك: ما إذا كان التغيير يحدث فورًا أو ينتظر في قائمة الانتظار، أو يحتاج إلى موافقة شخص آخر

• المسارات البديلة: نفس المهمة التي يتم الوصول إليها من شاشة مختلفة، أو النسخة الشاملة لإجراء واحد

• ماذا تفعل عندما يفشل: رسالة الخطأ التي من المرجح أن يواجهها القارئ، وما الذي تعنيه

مثال: توثيق ميزة جديدة

تطلق شركة SaaS ميزة الفوترة. بدلًا من كتابة الدليل، والتقاط لقطات الشاشة، وتسجيل جولة منفصلة، يقوم مدير منتج بتسجيل سير العمل مرة واحدة أثناء اختباره.

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

أين تساعد مُولّدات توثيق البرامج بالذكاء الاصطناعي

• جولات توضيحية لميزات المنتج: توثيق للميزة يجب أن يصدر مع الإطلاق بدلًا من أن يأتي بعده

• تدريب البرامج والعمليات الداخلية: سير عمل الإدارة، والأدوات الداخلية، والشاشات التي لم يكتب أحد عنها

• تهيئة المستخدمين للبرنامج: يتعلم القادمون الجدد المنتج من الجولة التوضيحية، ثم يعملون من الدليل المكتوب

• أدلة المنتج للعملاء والدعم: مقالات المساعدة وأدلة استكشاف الأخطاء وإصلاحها التي تتغير مع المنتج

لإنتاج عدة صيغ من تسجيل واحد، راجع مُولّد التوثيق متعدد الصيغ. ولأتمتة دورة حياة التوثيق الأوسع خارج سير عمل البرامج، راجع برنامج أتمتة التوثيق.

الحفاظ على توثيق البرامج محدثًا

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

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

ما الذي لا يفعله هذا

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

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