22 अगस्त 2026
Barkan डॉक्स नहीं, स्क्रीन क्यों पढ़ता है
डॉक्यूमेंटेशन प्रोडक्ट के बारे में आम तौर पर बताता है। DOM उसे इस यूज़र के लिए, ठीक इसी पल बताता है। एक नज़र इस पर कि Barkan किसी लाइव पेज को ऐसी चीज़ में कैसे बदलता है, जिस पर मॉडल काम कर सके।
जब हमने Barkan बनाना शुरू किया, तो सबसे सीधा आर्किटेक्चर वही था जो बाकी सब लॉन्च कर चुके थे: प्रोडक्ट के डॉक्यूमेंटेशन को एम्बेड करना, सवाल से जुड़े टुकड़े निकालना, और मॉडल से जवाब लिखवाना। हमने पहले वही बनाया। वह इतना ठीक चला कि उसका डेमो दिखाया जा सके, और इतना खराब कि उसे लॉन्च न किया जा सके, और नाकामी का तरीका हर बार एक ही था — जवाब प्रोडक्ट के बारे में सही था और यूज़र के बारे में गलत। यह पोस्ट उसके बाद लिए गए फ़ैसले के बारे में है: इसके बजाय हर जवाब को लाइव रेंडर हुए इंटरफ़ेस पर टिकाना, और इसमें असल में क्या-क्या लगता है।
वह नाकामी, जिसने आर्किटेक्चर बदल दिया
डॉक्स पर ट्रेन हुए वर्ज़न को तोड़ने वाला सवाल बिल्कुल मामूली था। एक टेस्टर ने पूछा, “दूसरी सीट कैसे जोड़ूँ?” और उसे हेल्प सेंटर से सीधे उठाया गया, छह स्टेप का साफ़-सुथरा जवाब मिला। चौथे स्टेप में मेंबर जोड़ें पर क्लिक करने को कहा गया था। टेस्टर की स्क्रीन पर वह बटन ग्रे था, और उसके टूलटिप में लिखा था कि Launch प्लान में सिर्फ़ एक सीट मिलती है।
जवाब मनगढ़ंत नहीं था। वह आम तौर पर सच था, और इस खास मामले में बेकार। मॉडल को अंदाज़ा ही नहीं था कि बटन डिसेबल है, क्योंकि डॉक्यूमेंटेशन में ऐसा कुछ नहीं था जो उसे बता सके कि इस अकाउंट की स्क्रीन इस वक्त कैसी दिखती है।
यही हर उस असिस्टेंट की बुनियादी सीमा है, जिसका ज्ञान प्रोडक्ट के बारे में लिखी गई बातों से आता है: वह प्रोडक्ट को वैसा जानता है जैसा वह डिज़ाइन हुआ, वैसा नहीं जैसा वह इस यूज़र के लिए रेंडर हुआ। और इन दोनों के बीच का फ़ासला ठीक वही जगह है, जहाँ यूज़र अटकते हैं।
अगर जवाब किसी ऐसी चीज़ पर टिका है जिसे यूज़र देख सकता है, तो मॉडल को भी उसे देख पाना चाहिए। डॉक्यूमेंटेशन को क्यों समझाने की छूट है; कहाँ बताने का हक सिर्फ़ लाइव इंटरफ़ेस को है।
“स्क्रीन पढ़ने” का मतलब क्या है
इसका मतलब स्क्रीनशॉट नहीं है, और न ही पूरा HTML उठाकर प्रॉम्प्ट में डाल देना। दोनों लुभाते हैं और दोनों नाकाम होते हैं — स्क्रीनशॉट में वह ढाँचा खो जाता है जिसकी मॉडल को ऐक्शन लेने के लिए ज़रूरत है, और किसी मॉडर्न ऐप का कच्चा HTML सैकड़ों किलोबाइट का फ़्रेमवर्क वाला शोर होता है, जिसमें काम का सिग्नल दबा रहता है।
इसके बजाय, जब यूज़र कुछ पूछता है, तो विजेट रेंडर हुए डॉक्यूमेंट का एक समृद्ध स्नैपशॉट कैप्चर करता है और उसे सवाल के साथ API को भेजता है। मोटे तौर पर उसमें ये चीज़ें होती हैं:
लेयर · इसमें क्या होता है · यह क्यों मायने रखता है
इंटरैक्टिव एलिमेंट · बटन, लिंक, इनपुट, एक स्थिर रेफ़रेंस और ऐक्सेसिबल लेबल के साथ · ताकि मॉडल किसी खास कंट्रोल की ओर इशारा कर सके और उस पर ऐक्शन ले सके
आपसी संबंध · कौन-सा लेबल किस इनपुट का है, कौन-सा बटन किस फ़ॉर्म का · “ईमेल फ़ील्ड” को एक ठोस एलिमेंट में बदल देता है
UI तथ्य · डिसेबल स्थिति, चुने गए टैब, बैज, गिनती, वैलिडेशन एरर · “Launch पर ग्रे” वाली वह जानकारी, जो डॉक्स के पास कभी थी ही नहीं
कंटेंट ब्लॉक · दिखने वाले हेडिंग और टेक्स्ट, डुप्लिकेट हटाकर और छोटा करके · पेज समझने लायक संदर्भ, पूरा पेज नहीं
फ़ॉर्म का सारांश · क्या भरा है, क्या खाली है, क्या अमान्य है · मॉडल अधूरा छूटा वर्कफ़्लो वहीं से आगे बढ़ा पाता है
सक्रिय सतहें और स्क्रॉल की स्थिति · खुले मोडल, ड्रॉअर, मौजूदा व्यूपोर्ट · “स्क्रीन पर नहीं” और “मौजूद ही नहीं” में फ़र्क करता है
पेज मेटा · रूट, टाइटल, अलाउ-लिस्ट वाले डेटा एट्रिब्यूट · कम खर्च में भरोसेमंद दिशा-बोध
पूरी चीज़ छोटी, स्थिर और ईमानदार रहने के लिए बनी है। छोटी, ताकि सोचने की गुंजाइश छोड़ते हुए कॉन्टेक्स्ट बजट में समा जाए। स्थिर, ताकि एक ही एलिमेंट को हर टर्न में एक ही रेफ़रेंस मिले — इसी से इशारा करना और कई स्टेप वाले ऐक्शन मुमकिन होते हैं। ईमानदार, ताकि मॉडल को कभी ऐसा कंट्रोल न दिखे, जो यूज़र को नहीं दिखता।
इससे खड़ी होने वाली तीन इंजीनियरिंग समस्याएँ
DOM पर टिकने से “यूज़र के बारे में गलत” वाली समस्या हल हो जाती है, और तुरंत तीन नई खड़ी हो जाती हैं। तीनों झेलने लायक हैं, पर वे असली हैं।
1. इंटरफ़ेस हिलता रहता है
डॉक्यूमेंटेशन का इंडेक्स तब बदलता है, जब कोई डॉक एडिट करता है। DOM तब बदलता है, जब कुछ भी होता है: कोई ड्रॉपडाउन खुलता है, कोई टोस्ट दिखता है, किसी लिस्ट की लोडिंग पूरी होती है। एक सेकंड पहले लिया गया स्नैपशॉट ऐसे पेज का वर्णन करता है, जो अब मौजूद ही नहीं।
हम इसे दो तरह से संभालते हैं। स्नैपशॉट पेज के थमने के बाद कैप्चर होता है — हम चल रही नेटवर्क गतिविधि और लेआउट के शांत होने का इंतज़ार करते हैं, एक तय सीमा के साथ, ताकि कोई शोरगुल वाला पेज जवाब को हमेशा के लिए अटका न सके। और ऐक्शन मोड में, हर ऐक्शन के बाद, अगला स्टेप तय होने से पहले, चुपचाप दोबारा कैप्चर होता है, ताकि मॉडल हमेशा पेज के उसी रूप पर काम करे जैसा वह अभी है, वैसा नहीं जैसा वह था।
2. अस्थिर ट्री पर स्थिर रेफ़रेंस
मॉडल से “तीसरे बटन पर क्लिक करो” कहना नाज़ुक है। उससे “id b17 वाले एलिमेंट पर क्लिक करो” कहना तभी काम करता है, जब अगले टर्न में भी b17 का मतलब वही हो। मॉडर्न फ़्रेमवर्क ताबड़तोड़ री-रेंडर करते हैं, इसलिए हम DOM की पहचान के भरोसे नहीं रह सकते।
हमारे रेफ़रेंस उन्हीं चीज़ों से बनते हैं, जिनसे कोई इंसान एलिमेंट को पहचानता — उसका रोल, उसका लेबल, अपने साथ वाले एलिमेंट्स के बीच उसकी जगह, उसे घेरने वाला लैंडमार्क — और हम रेफ़रेंस से लाइव नोड तक का एक थोड़ी देर टिकने वाला मैप रखते हैं। जब मैप पुराना पड़ जाता है, तो ऐक्शन खुलकर फ़ेल होता है और मॉडल गलत चीज़ पर क्लिक करने के बजाय पेज को दोबारा पढ़ता है। ऐसा फ़ेल ऐक्शन जो आपको दिखे, गलत एलिमेंट पर हुए कामयाब ऐक्शन से कहीं बेहतर है।
3. क्या नहीं भेजना है
किसी असली प्रोडक्ट के समृद्ध स्नैपशॉट में असली डेटा होता है: टेबल में ग्राहकों के नाम, किसी इनवॉइस का टोटल, फ़ॉर्म फ़ील्ड में कोई ईमेल। यह सब डिफ़ॉल्ट रूप से मॉडल को भेज देना मंज़ूर नहीं, और “हमें संदर्भ के लिए यह चाहिए” कोई ठोस वजह नहीं है।
स्नैपशॉट पेज से निकलने से पहले ही क्लाइंट पर छाँटकर छोटा कर दिया जाता है। दिखने वाला टेक्स्ट छोटा किया जाता है और उसके डुप्लिकेट हटाए जाते हैं, इनपुट की वैल्यू कॉपी करने के बजाय उन्हें भरा / खाली / अमान्य के रूप में संक्षेप में बताया जाता है, और सिर्फ़ अलाउ-लिस्ट में शामिल डेटा एट्रिब्यूट ही आगे भेजे जाते हैं। लक्ष्य यह है कि मॉडल को इतना पता हो कि ग्राहकों की 48 पंक्तियों वाली एक टेबल है और उसके ऊपर एक सर्च बॉक्स है, यह नहीं कि ग्राहक कौन हैं।
डेटा को कम से कम रखने की कीमत कभी-कभी एक जवाब से चुकानी पड़ती है। अगर यूज़र पूछे, “इस इनवॉइस का टोटल गलत क्यों है?”, तो मॉडल वह संख्या नहीं देख सकता। हमें लगता है कि यही सही डिफ़ॉल्ट है: वह यूज़र को उस फ़ील्ड की ओर इशारा कर सकता है और समझा सकता है कि टोटल कैसे निकाला जाता है, और वह आँकड़ा कभी पेज से बाहर नहीं जाता।
बताने के बजाय दिखाना
जब मॉडल उसी इंटरफ़ेस पर टिका होता है जिसे यूज़र देख रहा है, तो कुछ ऐसा मुमकिन हो जाता है जो डॉक्स पर ट्रेन हुआ कोई असिस्टेंट नहीं कर सकता: वह वर्णन करना छोड़कर इशारा करना शुरू कर सकता है।
जब जवाब में किसी एलिमेंट का ज़िक्र होता है, तो विजेट असली पेज पर कर्सर को उस तक ले जाता है और इंतज़ार करता है। कई स्टेप वाले वर्कफ़्लो में वही कर्सर यूज़र को एक कंट्रोल से दूसरे कंट्रोल तक ले चलता है — पेज बदलने पर भी, क्योंकि नए रूट पर स्नैपशॉट दोबारा बनता है। निर्देश और इंटरफ़ेस एक ही चीज़ बन जाते हैं, और डॉक्यूमेंटेशन को थकाऊ बनाने वाला अनुवाद का कदम बस गायब हो जाता है।
हर असिस्टेंट आपको बता सकता है कि बटन कहाँ है। फ़र्क इसमें है कि क्या वह देख पाता है कि आप पहले से ही गलत पेज पर हैं।
डॉक्स अब भी कहाँ काम आते हैं
इसका मतलब यह नहीं कि मॉडल के लिए डॉक्यूमेंटेशन बेकार है। मतलब यह है कि उसका काम अलग है। डॉक्स इरादा बताते हैं — कोई फ़ीचर किसलिए है, उसे कब इस्तेमाल करना है, किसी सेटिंग का मतलब क्या है — और स्क्रीन स्थिति बताती है। अच्छे जवाब को अक्सर दोनों चाहिए: नॉलेज बेस बताता है कि वेबहुक तीन बार दोबारा कोशिश करते हैं, और स्क्रीन दिखाती है कि इस वेबहुक की आखिरी डिलीवरी फ़ेल हुई।
इसलिए Barkan नॉलेज बेस से जानकारी लेता ज़रूर है, पर स्क्रीन पढ़ने के बाद, और जब दोनों में टकराव हो, तो स्क्रीन की बात मानी जाती है। अगर डॉक्स कहते हैं कि मेंबर जोड़ें बटन है और स्क्रीन दिखाती है कि वह डिसेबल है, तो जवाब डिसेबल बटन के बारे में होगा।
– डॉक्स पर नहीं, रेंडर हुए इंटरफ़ेस पर टिकें। “आम तौर पर सच” सबसे महँगी किस्म की गलती है।
– पिक्सेल या कच्चा HTML नहीं, ढाँचा भेजें: इंटरैक्टिव एलिमेंट, आपसी संबंध, UI तथ्य, संक्षेप में कंटेंट।
– पेज के थमने के बाद कैप्चर करें और हर ऐक्शन के बाद दोबारा कैप्चर करें; DOM लगातार खिसकता निशाना है।
– क्लाइंट पर ही डेटा छाँटें। मॉडल को डेटा की शक्ल पता होनी चाहिए, डेटा नहीं।
– वर्णन नहीं, इशारा करें। एलिमेंट दिख सकता है, तो उसे दिखाया भी जा सकता है।
इंस्टॉल अब भी बस एक लाइन है
एक जायज़ चिंता यह है कि “रेंडर हुआ इंटरफ़ेस पढ़ता है” का मतलब गहरा इंटीग्रेशन होगा। ऐसा नहीं है। विजेट उसी लेआउट में बस एक स्क्रिप्ट टैग है, जिसे आप पहले से रेंडर करते हैं; वह शैडो DOM में अपना रूट माउंट करता है, ब्राउज़र के अंदर से पेज को देखता है, और उसे न रूट एनोटेशन चाहिए, न कंपोनेंट रैपर।
<script async src="https://trybarkan.com/widget.js" data-barkan-site="site_your_key"></script>ऊपर बताया गया सब कुछ उसी स्क्रिप्ट में होता है। जिस प्रोडक्ट पर वह इंस्टॉल है, उसे यह जानने की भी ज़रूरत नहीं कि Barkan मौजूद है।
स्निपेट इंस्टॉल करें, अपना ऐप खोलें, और उससे कुछ ऐसा पूछें जिसका जवाब आपके डॉक्स नहीं दे सकते। शुरुआत के लिए $25 के क्रेडिट, कार्ड की ज़रूरत नहीं।
“ज़्यादातर यूज़र्स एक और जवाब नहीं चाहते। वे चाहते हैं कि कोई रास्ता दिखा दे, या काम ही कर दे। पूरा प्रोडक्ट बस इतना ही है।”
Gabriel Lancelot
को-फ़ाउंडर, Barkan
