لماذا يقرأ Barkan الشاشة، لا الوثائق

2. مراجع ثابتة على شجرة غير ثابتة

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

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

3. ما الذي لا نرسله

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

تُقلَّص اللقطة إلى الحد الأدنى في المتصفح قبل أن تغادر الصفحة. يُقتطع النص الظاهر ويُزال تكراره، وتُلخَّص قيم حقول الإدخال بعبارة ممتلئ / فارغ / غير صالح بدل نسخها، ولا تُمرَّر إلا سمات data الواردة في قائمة السماح. والهدف أن يعرف النموذج أنّ هناك جدول عملاء من 48 صفًا فوقه مربع بحث، لا أن يعرف من هم العملاء.

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

أن تُري بدل أن تشرح

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

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

كل مساعد يستطيع أن يخبرك أين الزر. الفرق هو: هل يستطيع أن يرى أنك تنظر أصلًا إلى الصفحة الخطأ؟

حيث تظل الوثائق مهمة

لا يعني أيٌّ من هذا أن التوثيق عديم الفائدة للنموذج، بل إن له مهمة مختلفة. فالوثائق تحمل الغاية: ما الغرض من الميزة، ومتى تُستخدم، وماذا يعني إعداد ما. أما الشاشة فتحمل الحالة. والإجابة الجيدة تحتاج غالبًا إلى الاثنين: قاعدة المعرفة تشرح أن webhooks تعيد المحاولة ثلاث مرات، والشاشة تُظهر أن آخر إرسال عبر هذا الـ webhook قد فشل.

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

– ارتكز على الواجهة المعروضة، لا على الوثائق. «صحيح بوجه عام» هو أغلى أنواع الخطأ.

– أرسل البنية، لا البكسلات ولا HTML الخام: العناصر التفاعلية، والعلاقات، وحقائق الواجهة، والمحتوى الملخَّص.

– التقط بعد أن تستقر الصفحة، وأعد الالتقاط بعد كل إجراء؛ فشجرة DOM هدف متحرك.

– قلّص البيانات في المتصفح. ينبغي أن يعرف النموذج شكل البيانات، لا البيانات نفسها.

– أشِر، ولا تصف. متى استطعت أن ترى العنصر، استطعت أن تُريه.

التثبيت ما زال سطرًا واحدًا

ومن المخاوف المشروعة أن تعني عبارة «يقرأ الواجهة المعروضة» تكاملًا عميقًا. لكنها لا تعني ذلك. فالشريط ليس سوى وسم script واحد في القالب الذي تعرضه أصلًا؛ يُنشئ جذره الخاص داخل shadow DOM، ويراقب الصفحة من داخل المتصفح، ولا يحتاج إلى أي تعليقات توضيحية على المسارات أو أغلفة للمكوّنات.

<script async src="https://trybarkan.com/widget.js" data-barkan-site="site_your_key"></script>

كل ما وصفناه أعلاه يحدث داخل ذلك الـ script. والمنتج الذي يُثبَّت عليه لا يحتاج إلى أن يعرف بوجود Barkan أصلًا.

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