22 اگست 2026
Barkan ڈاکس کے بجائے اسکرین کیوں پڑھتا ہے
ڈاکیومنٹیشن پروڈکٹ کو عمومی طور پر بیان کرتی ہے۔ DOM اسے اسی صارف کے لیے، اسی لمحے بیان کرتا ہے۔ اندر سے ایک نظر کہ Barkan ایک لائیو پیج کو ایسی چیز میں کیسے بدلتا ہے جس پر ماڈل عمل کر سکے۔
جب ہم نے Barkan بنانا شروع کیا تو سامنے کا آرکیٹیکچر وہی تھا جو باقی سب لانچ کر چکے تھے: پروڈکٹ کی ڈاکیومنٹیشن کو ایمبیڈ کریں، ہر سوال کے لیے متعلقہ ٹکڑے نکالیں، اور ماڈل سے جواب لکھوا لیں۔ ہم نے پہلے یہی بنایا۔ یہ اتنا اچھا چلا کہ ڈیمو دکھایا جا سکے، اور اتنا برا کہ لانچ نہ کیا جا سکے، اور ناکامی ہمیشہ ایک ہی شکل میں سامنے آتی تھی — جواب پروڈکٹ کے بارے میں درست اور صارف کے بارے میں غلط ہوتا تھا۔ یہ تحریر اس کے بعد کیے گئے فیصلے کے بارے میں ہے: اس کے بجائے ہر جواب کی بنیاد لائیو، رینڈر شدہ انٹرفیس پر رکھنا، اور یہ کہ اس کے لیے اصل میں کیا کچھ کرنا پڑتا ہے۔
وہ ناکامی جس نے آرکیٹیکچر بدل دیا
جس سوال نے ڈاکس پر تربیت یافتہ ورژن کو توڑا، وہ بالکل معمولی تھا۔ ایک ٹیسٹر نے پوچھا ”دوسری سیٹ کیسے شامل کروں؟“ اور اسے ہیلپ سینٹر سے سیدھا اٹھایا ہوا، چھ قدموں کا صاف ستھرا جواب ملا۔ چوتھے قدم میں ممبر شامل کریں پر کلک کرنے کو کہا گیا تھا۔ ٹیسٹر کی اسکرین پر وہ بٹن مدھم تھا، اور ساتھ ایک ٹول ٹپ بتا رہا تھا کہ Launch پلان میں صرف ایک سیٹ کی گنجائش ہے۔
جواب من گھڑت نہیں تھا۔ عمومی طور پر وہ سچ تھا، اور اس خاص صورت میں بے کار۔ ماڈل کو اندازہ ہی نہیں تھا کہ بٹن غیر فعال ہے، کیونکہ ڈاکیومنٹیشن میں ایسا کچھ نہیں تھا جو اسے بتا سکتا کہ اس اکاؤنٹ کی اسکرین اس وقت کیسی دکھائی دے رہی ہے۔
یہی ہر اس اسسٹنٹ کی بنیادی حد ہے جس کا علم پروڈکٹ کے بارے میں لکھی گئی عبارت سے آتا ہے: وہ پروڈکٹ کو ویسی جانتا ہے جیسی وہ ڈیزائن ہوئی، ویسی نہیں جیسی وہ اس صارف کی اسکرین پر رینڈر ہوئی۔ اور صارف ٹھیک انہی دونوں کے بیچ کے فرق میں پھنستے ہیں۔
اگر جواب کسی ایسی چیز پر منحصر ہے جو صارف دیکھ سکتا ہے، تو ماڈل کو بھی اسے دیکھ پانا چاہیے۔ ڈاکیومنٹیشن کو کیوں سمجھانے کا حق ہے؛ کہاں بتانے کا حق صرف لائیو انٹرفیس کو ہے۔
”اسکرین پڑھنے“ کا مطلب کیا ہے
اس کا مطلب اسکرین شاٹس نہیں، اور نہ ہی پورا HTML اٹھا کر پرامپٹ میں ڈال دینا۔ دونوں راستے پرکشش ہیں اور دونوں ناکام رہتے ہیں — اسکرین شاٹس میں وہ ڈھانچہ کھو جاتا ہے جو ماڈل کو عمل کرنے کے لیے چاہیے، اور کسی جدید ایپ کا خام HTML فریم ورک کے شور کے سینکڑوں کلوبائٹس ہوتا ہے جن کے نیچے کام کی بات دبی ہوتی ہے۔
اس کے بجائے، جب صارف کچھ پوچھتا ہے تو ویجٹ رینڈر شدہ پیج کا ایک افزودہ اسنیپ شاٹ لیتا ہے اور اسے سوال کے ساتھ API کو بھیج دیتا ہے۔ موٹے طور پر اس میں یہ شامل ہوتا ہے:
پرت · اس میں کیا ہوتا ہے · یہ کیوں اہم ہے
انٹرایکٹو ایلیمنٹس · بٹن، لنکس، اِن پٹس، ایک مستحکم ریفرنس اور قابلِ رسائی لیبل کے ساتھ · تاکہ ماڈل کسی مخصوص کنٹرول کی طرف اشارہ کر سکے اور اس پر عمل کر سکے
تعلقات · کون سا لیبل کس اِن پٹ کا ہے، کون سا بٹن کس فارم کا ہے · ”ای میل والا خانہ“ ایک ٹھوس ایلیمنٹ بن جاتا ہے
انٹرفیس کے حقائق · غیر فعال حالتیں، منتخب ٹیبز، بیجز، گنتیاں، ویلیڈیشن ایررز · ”Launch پر مدھم“ والی وہ معلومات جو ڈاکس کے پاس کبھی تھیں ہی نہیں
مواد کے بلاکس · نظر آنے والی سرخیاں اور متن، تکرار کے بغیر اور مختصر کیا ہوا · پیج سمجھنے کے لیے کافی سیاق و سباق، پورا پیج نہیں
فارم کے خلاصے · کیا بھرا ہے، کیا خالی ہے، کیا غلط ہے · ماڈل ادھورا ورک فلو وہیں سے آگے بڑھا سکتا ہے
فعال سطحیں اور اسکرول کی حالت · کھلے موڈلز، ڈرارز، موجودہ ویو پورٹ · ”اسکرین پر نہیں“ اور ”موجود ہی نہیں“ میں فرق کرتا ہے
پیج کی میٹا معلومات · روٹ، ٹائٹل، اجازت یافتہ فہرست کے ڈیٹا ایٹریبیوٹس · سستی اور قابلِ اعتماد سمت شناسی
یہ پورا ڈھانچہ اس طرح بنایا گیا ہے کہ چھوٹا، مستحکم اور دیانتدار ہو۔ چھوٹا، تاکہ کانٹیکسٹ کے بجٹ میں سما جائے اور سوچنے کی گنجائش بھی بچے۔ مستحکم، تاکہ ایک ہی ایلیمنٹ کو ہر باری میں ایک ہی ریفرنس ملے، اور یہی اشارہ کرنے اور کئی مراحل والے ایکشنز کو ممکن بناتا ہے۔ دیانتدار، تاکہ ماڈل کو کبھی ایسا کنٹرول نظر نہ آئے جو صارف کو نظر نہیں آتا۔
اس سے پیدا ہونے والے تین انجینئرنگ مسائل
جوابوں کی بنیاد DOM پر رکھنے سے ”صارف کے بارے میں غلط“ والا مسئلہ حل ہو جاتا ہے، اور فوراً تین نئے مسئلے کھڑے ہو جاتے ہیں۔ یہ سب اس قیمت کے لائق ہیں، مگر ہیں حقیقی۔
1. انٹرفیس بدلتا رہتا ہے
ڈاکیومنٹیشن کا انڈیکس تب بدلتا ہے جب کوئی کسی دستاویز میں ترمیم کرے۔ DOM تب بدلتا ہے جب کچھ بھی ہو: کوئی ڈراپ ڈاؤن کھلے، کوئی ٹوسٹ نوٹیفکیشن آئے، کوئی لسٹ لوڈ ہو جائے۔ ایک سیکنڈ پہلے لیا گیا اسنیپ شاٹ ایسے پیج کو بیان کرتا ہے جو اب موجود ہی نہیں۔
ہم اسے دو طرح سے سنبھالتے ہیں۔ اسنیپ شاٹ تب لیا جاتا ہے جب پیج ٹھہر جائے — ہم انتظار کرتے ہیں کہ جاری نیٹ ورک سرگرمی اور لے آؤٹ کی تبدیلیاں تھم جائیں، مگر ایک حد کے ساتھ، تاکہ کوئی ہلچل والا پیج جواب کو ہمیشہ کے لیے نہ روک سکے۔ اور ایکشن موڈ میں ہر ایکشن کے بعد، اگلا قدم طے ہونے سے پہلے، خاموشی سے نیا اسنیپ شاٹ لیا جاتا ہے، تاکہ ماڈل ہمیشہ پیج کی موجودہ حالت پر عمل کرے، پچھلی حالت پر نہیں۔
2. غیر مستحکم ٹری پر مستحکم ریفرنسز
ماڈل سے یہ کہنا کہ ”تیسرے بٹن پر کلک کریں“ کمزور طریقہ ہے۔ یہ کہنا کہ ”id b17 والے ایلیمنٹ پر کلک کریں“ تبھی کام کرتا ہے جب اگلی باری میں بھی b17 کا مطلب وہی ہو۔ جدید فریم ورکس دھڑا دھڑ دوبارہ رینڈر کرتے ہیں، اس لیے ہم DOM کی شناخت پر بھروسہ نہیں کر سکتے۔
ہمارے ریفرنسز ان چیزوں سے بنتے ہیں جن سے کوئی انسان ایلیمنٹ کو پہچانتا — اس کا رول، اس کا لیبل، ساتھ والے ایلیمنٹس میں اس کی جگہ، اور وہ لینڈ مارک جس کے اندر وہ موجود ہے — اور ہم ریفرنس سے لائیو نوڈ تک کا ایک مختصر مدت والا نقشہ رکھتے ہیں۔ جب نقشہ پرانا ہو جائے تو ایکشن کھل کر ناکام ہوتا ہے، اور ماڈل غلط چیز پر کلک کرنے کے بجائے پیج دوبارہ پڑھتا ہے۔ ایسا ناکام ایکشن جو نظر آئے، غلط ایلیمنٹ پر کامیاب ایکشن سے کہیں بہتر ہے۔
3. کیا نہیں بھیجنا
کسی حقیقی پروڈکٹ کے افزودہ اسنیپ شاٹ میں حقیقی ڈیٹا ہوتا ہے: کسی ٹیبل میں کسٹمرز کے نام، کسی انوائس کی کل رقم، کسی فارم کے خانے میں ای میل۔ یہ سب کچھ ڈیفالٹ طور پر ماڈل کو بھیج دینا قابلِ قبول نہیں، اور ”ہمیں سیاق و سباق کے لیے چاہیے“ کوئی کافی وجہ نہیں۔
پیج سے نکلنے سے پہلے ہی کلائنٹ پر اسنیپ شاٹ کو کم سے کم کر دیا جاتا ہے۔ نظر آنے والا متن مختصر کیا جاتا ہے اور اس میں سے تکرار نکال دی جاتی ہے، اِن پٹ کی ویلیوز کاپی کرنے کے بجائے ان کا خلاصہ صرف بھرا / خالی / غلط کی صورت میں جاتا ہے، اور صرف اجازت یافتہ فہرست والے ڈیٹا ایٹریبیوٹس آگے بھیجے جاتے ہیں۔ مقصد یہ ہے کہ ماڈل کو بس اتنا معلوم ہو کہ کسٹمرز کا ایک ٹیبل ہے جس میں 48 قطاریں ہیں اور اس کے اوپر سرچ باکس ہے، یہ نہیں کہ کسٹمرز کون ہیں۔
ڈیٹا کم سے کم رکھنے کی قیمت کبھی کبھار ایک جواب کی صورت میں چکانی پڑتی ہے۔ اگر صارف پوچھے ”اس انوائس کی کل رقم غلط کیوں ہے؟“ تو ماڈل وہ رقم دیکھ ہی نہیں سکتا۔ ہمارے خیال میں یہی درست ڈیفالٹ ہے: وہ صارف کو اس خانے کی طرف اشارہ کر سکتا ہے اور سمجھا سکتا ہے کہ کل رقم کیسے نکلتی ہے، اور وہ عدد کبھی پیج سے باہر نہیں جاتا۔
بتانے کے بجائے دکھانا
جب ماڈل کی بنیاد اسی انٹرفیس پر ہو جسے صارف دیکھ رہا ہے، تو وہ ممکن ہو جاتا ہے جو ڈاکس پر تربیت یافتہ کوئی اسسٹنٹ نہیں کر سکتا: وہ بیان کرنا چھوڑ کر اشارہ کرنا شروع کر سکتا ہے۔
جب جواب میں کسی ایلیمنٹ کا ذکر ہو تو ویجٹ اصل پیج پر کرسر اس تک لے جاتا ہے اور انتظار کرتا ہے۔ کئی مراحل والے ورک فلو میں یہی کرسر صارف کو ایک کنٹرول سے دوسرے کنٹرول تک لے کر چلتا ہے — ایک پیج سے دوسرے پیج پر جانے کے بعد بھی، کیونکہ نئے روٹ پر اسنیپ شاٹ دوبارہ بنتا ہے۔ ہدایت اور انٹرفیس ایک ہی چیز بن جاتے ہیں، اور ترجمے کا وہ مرحلہ، جو ڈاکیومنٹیشن کو تھکا دینے والا بناتا ہے، سرے سے غائب ہو جاتا ہے۔
ہر اسسٹنٹ آپ کو بتا سکتا ہے کہ بٹن کہاں ہے۔ فرق اس بات کا ہے کہ کیا وہ یہ دیکھ سکتا ہے کہ آپ پہلے ہی غلط پیج پر ہیں۔
ڈاکس اب بھی کہاں اہم ہیں
اس سب کا مطلب یہ نہیں کہ ماڈل کے لیے ڈاکیومنٹیشن بے کار ہے۔ مطلب یہ ہے کہ اس کا کام مختلف ہے۔ ڈاکس مقصد بتاتے ہیں — کوئی فیچر کس لیے ہے، اسے کب استعمال کریں، کسی سیٹنگ کا مطلب کیا ہے — اور اسکرین حالت بتاتی ہے۔ اچھے جواب کو اکثر دونوں کی ضرورت ہوتی ہے: نالج بیس بتاتا ہے کہ ویب ہُکس تین بار دوبارہ کوشش کرتے ہیں، اور اسکرین دکھاتی ہے کہ اس ویب ہُک کی پچھلی ڈیلیوری ناکام ہوئی تھی۔
اس لیے Barkan نالج بیس سے معلومات لیتا ضرور ہے، مگر اسکرین پڑھنے کے بعد، اور جب بھی دونوں میں اختلاف ہو تو اسکرین کی بات مانی جاتی ہے۔ اگر ڈاکس کہیں کہ ممبر شامل کریں کا بٹن موجود ہے اور اسکرین بتائے کہ وہ غیر فعال ہے، تو جواب اسی غیر فعال بٹن کے بارے میں ہوگا۔
– جواب کی بنیاد ڈاکس پر نہیں، رینڈر شدہ انٹرفیس پر رکھیں۔ ”عمومی طور پر درست“ غلطی کی سب سے مہنگی قسم ہے۔
– پکسلز یا خام HTML نہیں، ڈھانچہ بھیجیں: انٹرایکٹو ایلیمنٹس، تعلقات، انٹرفیس کے حقائق، خلاصہ شدہ مواد۔
– اسنیپ شاٹ پیج ٹھہرنے کے بعد لیں، اور ہر ایکشن کے بعد دوبارہ لیں؛ DOM ایک متحرک ہدف ہے۔
– ڈیٹا کلائنٹ پر ہی کم سے کم کریں۔ ماڈل کو ڈیٹا کی شکل معلوم ہونی چاہیے، ڈیٹا نہیں۔
– بیان نہ کریں، اشارہ کریں۔ جب ایلیمنٹ نظر آ رہا ہو تو اسے دکھایا بھی جا سکتا ہے۔
انسٹال اب بھی ایک ہی لائن ہے
ایک معقول خدشہ یہ ہے کہ ”رینڈر شدہ انٹرفیس پڑھتا ہے“ کا مطلب گہری انٹیگریشن ہے۔ ایسا نہیں ہے۔ ویجٹ اسی لے آؤٹ میں ایک اسکرپٹ ٹیگ ہے جو آپ پہلے سے رینڈر کر رہے ہیں؛ یہ shadow DOM کے اندر اپنا الگ root ماؤنٹ کرتا ہے، براؤزر کے اندر سے پیج کا مشاہدہ کرتا ہے، اور اسے نہ روٹ اینوٹیشنز چاہییں، نہ کمپوننٹ ریپرز۔
<script async src="https://trybarkan.com/widget.js" data-barkan-site="site_your_key"></script>اوپر بیان کی گئی ہر چیز اسی اسکرپٹ میں ہوتی ہے۔ جس پروڈکٹ پر یہ انسٹال ہو، اسے یہ جاننے کی بھی ضرورت نہیں کہ Barkan موجود ہے۔
اسنیپٹ انسٹال کریں، اپنی ایپ کھولیں، اور اس سے وہ بات پوچھیں جس کا جواب آپ کے ڈاکس نہیں دے سکتے۔ شروع کرنے کے لیے $25 کا مفت کریڈٹ، کارڈ کی ضرورت نہیں۔
”زیادہ تر صارفین کو ایک اور جواب نہیں چاہیے۔ وہ چاہتے ہیں کہ انہیں راستہ دکھایا جائے، یا کام ہی کر دیا جائے۔ پوری پروڈکٹ بس یہی ہے۔“
Gabriel Lancelot
شریک بانی، Barkan
