22 আগস্ট, 2026
Barkan কেন ডকস নয়, স্ক্রিন পড়ে
ডকুমেন্টেশন প্রোডাক্টের বর্ণনা দেয় সাধারণভাবে। DOM বর্ণনা দেয় এই ইউজারের জন্য, ঠিক এই মুহূর্তে। Barkan কীভাবে একটি লাইভ পেজকে এমন কিছুতে পরিণত করে, যার ওপর মডেল কাজ করতে পারে, তার ভেতরের গল্প।
Barkan বানাতে শুরু করার সময় সবচেয়ে স্বাভাবিক আর্কিটেকচার ছিল সেটাই, যা বাকি সবাই লঞ্চ করেছিল: প্রোডাক্টের ডকুমেন্টেশন এমবেড করা, প্রশ্ন এলে প্রাসঙ্গিক অংশগুলো খুঁজে আনা, আর মডেলকে দিয়ে উত্তর লেখানো। আমরাও প্রথমে সেটাই বানিয়েছিলাম। ডেমো দেখানো যায়, এতটা ভালো কাজ করত; লঞ্চ করা যায় না, এতটা খারাপ। আর ব্যর্থতার ধরন ছিল সবসময় একই — উত্তরটা প্রোডাক্টের ব্যাপারে ঠিক, অথচ ইউজারের ব্যাপারে ভুল। এই লেখা তার পরের সিদ্ধান্তটা নিয়ে: প্রতিটি উত্তরের ভিত্তি হবে লাইভ রেন্ডার হওয়া ইন্টারফেস, আর তার জন্য আসলে কী কী লাগে।
যে ব্যর্থতা আর্কিটেকচার বদলে দিল
ডকস-নির্ভর সংস্করণটাকে যে প্রশ্ন ভেঙে দিল, সেটা ছিল একেবারে সাদামাটা। একজন টেস্টার জিজ্ঞেস করলেন, “দ্বিতীয় একটা সিট যোগ করব কীভাবে?”, আর পেলেন হেল্প সেন্টার থেকে সোজা তুলে আনা ছয় ধাপের একটা পরিচ্ছন্ন উত্তর। চতুর্থ ধাপে বলা ছিল মেম্বার যোগ করুন-এ ক্লিক করতে। টেস্টারের স্ক্রিনে সেই বাটনটা ছিল ধূসর, সঙ্গে একটা টুলটিপ, যাতে লেখা Launch প্ল্যানে সিট একটাই।
উত্তরটা হ্যালুসিনেশন ছিল না। সাধারণভাবে সেটা ছিল সত্যি, আর এই নির্দিষ্ট ক্ষেত্রে অকেজো। বাটনটা যে নিষ্ক্রিয়, মডেলের সে ধারণাই ছিল না, কারণ এই অ্যাকাউন্টের স্ক্রিন এই মুহূর্তে কেমন দেখাচ্ছে, তা ডকুমেন্টেশনের কোনো কিছুই তাকে বলতে পারত না।
প্রোডাক্ট নিয়ে লেখা গদ্য থেকে যে অ্যাসিস্ট্যান্টের জ্ঞান আসে, তার মূল সীমাবদ্ধতা এটাই: সে প্রোডাক্টকে চেনে যেভাবে তা ডিজাইন করা হয়েছে, যেভাবে এই ইউজারের জন্য রেন্ডার হয়েছে সেভাবে নয়। আর ইউজাররা আটকে যান ঠিক এই দুইয়ের ফাঁকেই।
উত্তর যদি এমন কিছুর ওপর নির্ভর করে, যা ইউজার দেখতে পান, তাহলে মডেলকেও সেটা দেখতে পেতে হবে। ডকুমেন্টেশন ব্যাখ্যা করতে পারে কেন; কোথায়, তা বলার অধিকার শুধু লাইভ ইন্টারফেসের।
“স্ক্রিন পড়া” মানে কী
এর মানে স্ক্রিনশট নয়, আবার পুরো HTML প্রম্পটে ঢেলে দেওয়াও নয়। দুটোই লোভনীয়, আর দুটোই ব্যর্থ — স্ক্রিনশটে হারিয়ে যায় সেই কাঠামো, কাজ করতে যা মডেলের দরকার, আর আধুনিক অ্যাপের কাঁচা HTML মানে শত শত কিলোবাইট ফ্রেমওয়ার্কের কোলাহল, যার নিচে চাপা পড়ে থাকে কাজের সংকেতটুকু।
তার বদলে, ইউজার কিছু জিজ্ঞেস করলে উইজেট রেন্ডার হওয়া ডকুমেন্টের একটা সমৃদ্ধ স্ন্যাপশট নেয়, আর প্রশ্নের সঙ্গে সেটা এপিআই-তে পাঠায়। মোটামুটি এতে থাকে:
স্তর · এতে কী থাকে · কেন জরুরি
ইন্টারঅ্যাক্টিভ এলিমেন্ট · বাটন, লিংক, ইনপুট, স্থির রেফারেন্স আর অ্যাক্সেসিবল লেবেলসহ · যাতে মডেল নির্দিষ্ট একটি কন্ট্রোলকে দেখিয়ে দিতে আর তার ওপর কাজ করতে পারে
সম্পর্ক · কোন লেবেল কোন ইনপুটের, কোন বাটন কোন ফর্মের · “ইমেইলের ফিল্ড” কথাটাকে একটি নির্দিষ্ট এলিমেন্টে পরিণত করে
UI-এর তথ্য · নিষ্ক্রিয় অবস্থা, বাছাই করা ট্যাব, ব্যাজ, সংখ্যা, ভ্যালিডেশন এরর · “Launch প্ল্যানে ধূসর” ধরনের সেই তথ্য, যা ডকসে কখনো ছিল না
কনটেন্ট ব্লক · দৃশ্যমান হেডিং আর লেখা, পুনরাবৃত্তি বাদ দিয়ে ও ছেঁটে · পেজটা বোঝার মতো যথেষ্ট প্রসঙ্গ, পুরো পেজ নয়
ফর্মের সারাংশ · কী পূরণ হয়েছে, কী ফাঁকা, কী অবৈধ · মডেল আধখানা শেষ হওয়া ওয়ার্কফ্লো আবার ধরতে পারে
সক্রিয় অংশ আর স্ক্রলের অবস্থা · খোলা মোডাল, ড্রয়ার, বর্তমান ভিউপোর্ট · “স্ক্রিনে নেই” আর “অস্তিত্বই নেই”-এর মধ্যে পার্থক্য করে
পেজের মেটা · রুট, টাইটেল, অনুমোদিত তালিকার ডেটা অ্যাট্রিবিউট · সস্তা, নির্ভরযোগ্য দিকনির্দেশ
পুরো জিনিসটা বানানো হয়েছে ছোট, স্থির আর সৎ রাখার জন্য। ছোট, যাতে কনটেক্সট বাজেটে এঁটে যায় আর ভাবার জায়গাও থাকে। স্থির, যাতে প্রতি দফায় একই এলিমেন্ট একই রেফারেন্স পায়, আর এতেই দেখিয়ে দেওয়া ও একাধিক ধাপের কাজ সম্ভব হয়। সৎ, যাতে মডেল কখনো এমন কোনো কন্ট্রোল না দেখে, যা ইউজার দেখতে পান না।
এতে যে তিনটি ইঞ্জিনিয়ারিং সমস্যা তৈরি হয়
DOM-কে ভিত্তি করলে “ইউজারের ব্যাপারে ভুল” সমস্যার সমাধান হয়, আর সঙ্গে সঙ্গে জন্ম নেয় আরও তিনটি। তিনটিই মেনে নেওয়ার মতো, কিন্তু সমস্যাগুলো সত্যি।
1. ইন্টারফেস স্থির থাকে না
ডকুমেন্টেশনের ইনডেক্স বদলায় যখন কেউ একটা ডক এডিট করেন। DOM বদলায় যেকোনো কিছু ঘটলেই: একটা ড্রপডাউন খোলে, একটা টোস্ট নোটিফিকেশন দেখা দেয়, একটা লিস্ট লোড হওয়া শেষ হয়। এক সেকেন্ড আগে নেওয়া স্ন্যাপশট এমন এক পেজের বর্ণনা দেয়, যার আর অস্তিত্ব নেই।
আমরা এটা সামলাই দুভাবে। স্ন্যাপশট নেওয়া হয় পেজ থিতু হওয়ার পর — চলমান নেটওয়ার্ক অ্যাক্টিভিটি আর লেআউট শান্ত হওয়া পর্যন্ত আমরা অপেক্ষা করি, তবে একটা সীমা বেঁধে, যাতে অস্থির কোনো পেজ উত্তরকে অনন্তকাল আটকে রাখতে না পারে। আর ডু মোডে প্রতিটি কাজের পর, পরের ধাপ ঠিক করার আগে, নিঃশব্দে আবার স্ন্যাপশট নেওয়া হয়, তাই মডেল সবসময় কাজ করে পেজ এখন যেমন আছে তার ওপর, আগে যেমন ছিল তার ওপর নয়।
2. অস্থির ট্রিতে স্থির রেফারেন্স
মডেলকে “তৃতীয় বাটনে ক্লিক করো” বলা ভঙ্গুর। “b17 আইডির এলিমেন্টে ক্লিক করো” বলা কাজ করে কেবল তখনই, যদি পরের দফাতেও b17 মানে একই জিনিস হয়। আধুনিক ফ্রেমওয়ার্ক ঘনঘন রি-রেন্ডার করে, তাই DOM-এর নিজস্ব পরিচয়ের ওপর আমরা ভরসা করতে পারি না।
আমাদের রেফারেন্স তৈরি হয় সেসব জিনিস থেকে, যা দিয়ে একজন মানুষ এলিমেন্টটা চিনতেন — তার ভূমিকা, তার লেবেল, পাশের এলিমেন্টগুলোর মধ্যে তার অবস্থান, তাকে ঘিরে থাকা ল্যান্ডমার্ক — আর রেফারেন্স থেকে লাইভ নোড পর্যন্ত একটা স্বল্পস্থায়ী ম্যাপ আমরা রাখি। ম্যাপ পুরোনো হয়ে গেলে কাজটা খোলাখুলি ব্যর্থ হয়, আর মডেল ভুল জিনিসে ক্লিক না করে পেজটা আবার পড়ে। ভুল এলিমেন্টে সফল কাজের চেয়ে চোখে দেখা যায় এমন ব্যর্থ কাজ অনেক ভালো।
3. কী পাঠানো চলবে না
সত্যিকারের প্রোডাক্টের সমৃদ্ধ স্ন্যাপশটে থাকে সত্যিকারের ডেটা: টেবিলে কাস্টমারদের নাম, ইনভয়েসের মোট অঙ্ক, ফর্মের ফিল্ডে একটা ইমেইল। ডিফল্টভাবে এর সবটা মডেলের কাছে পাঠানো গ্রহণযোগ্য নয়, আর “প্রসঙ্গের জন্য দরকার” যথেষ্ট ভালো কারণ নয়।
পেজ ছাড়ার আগেই ক্লায়েন্টে স্ন্যাপশটটা ছোট করে আনা হয়। দৃশ্যমান লেখা ছেঁটে আর পুনরাবৃত্তি বাদ দিয়ে নেওয়া হয়, ইনপুটের মান কপি না করে সংক্ষেপে জানানো হয় পূরণ / ফাঁকা / অবৈধ হিসেবে, আর ডেটা অ্যাট্রিবিউটের মধ্যে শুধু অনুমোদিত তালিকারগুলোই পাঠানো হয়। লক্ষ্য হলো মডেল যেন শুধু এটুকু জানে যে 48 সারির একটা কাস্টমার টেবিল আছে আর তার ওপরে একটা সার্চ বক্স, কিন্তু কাস্টমাররা কারা, তা যেন না জানে।
ডেটা কমিয়ে আনার দাম মাঝে মাঝে একটা উত্তর দিয়ে চুকাতে হয়। ইউজার যদি জিজ্ঞেস করেন, “এই ইনভয়েসের মোট অঙ্কটা ভুল কেন?”, মডেল সংখ্যাটা দেখতে পায় না। আমাদের মতে ডিফল্ট হিসেবে এটাই ঠিক: মডেল ইউজারকে ফিল্ডটা দেখিয়ে দিতে পারে আর মোট অঙ্ক কীভাবে হিসাব হয় তা ব্যাখ্যা করতে পারে, অথচ অঙ্কটা কখনো পেজ ছেড়ে যায় না।
বলার বদলে দেখানো
ইউজার যে ইন্টারফেস দেখছেন, মডেল একবার সেটার ওপর দাঁড়ালে এমন কিছু সম্ভব হয়, যা ডকস দিয়ে ট্রেন করা কোনো অ্যাসিস্ট্যান্ট পারে না: বর্ণনা থামিয়ে সে দেখিয়ে দিতে শুরু করতে পারে।
উত্তরে কোনো এলিমেন্টের উল্লেখ থাকলে উইজেট আসল পেজে কার্সরটা সেখানে নিয়ে যায় এবং অপেক্ষা করে। একাধিক ধাপের ওয়ার্কফ্লো জুড়ে সেই কার্সর ইউজারকে এক কন্ট্রোল থেকে আরেক কন্ট্রোলে নিয়ে যায় — এক পেজ থেকে আরেক পেজে গেলেও, কারণ নতুন রুটে স্ন্যাপশট নতুন করে তৈরি হয়। নির্দেশনা আর ইন্টারফেস এক হয়ে যায়, আর যে অনুবাদের ধাপ ডকুমেন্টেশনকে এত ক্লান্তিকর করে তোলে, সেটা স্রেফ উধাও হয়ে যায়।
যেকোনো অ্যাসিস্ট্যান্টই বলে দিতে পারে বাটনটা কোথায়। পার্থক্য হলো, আপনি যে ইতিমধ্যে ভুল পেজে তাকিয়ে আছেন, সেটা সে দেখতে পায় কি না।
ডকস এখনো যেখানে জরুরি
এর কোনোটার মানে এই নয় যে মডেলের কাছে ডকুমেন্টেশন অকেজো। মানে হলো, এর কাজটা আলাদা। ডকস বহন করে উদ্দেশ্য — একটা ফিচার কীসের জন্য, কখন ব্যবহার করবেন, একটা সেটিংয়ের মানে কী — আর স্ক্রিন বহন করে অবস্থা। ভালো উত্তরে প্রায়ই দুটোই লাগে: নলেজ বেস ব্যাখ্যা করে যে ওয়েবহুক তিনবার রিট্রাই করে, আর স্ক্রিন দেখায় যে এই ওয়েবহুকের শেষ ডেলিভারি ব্যর্থ হয়েছে।
তাই Barkan নলেজ বেস থেকে তথ্য আনে ঠিকই, কিন্তু আনে স্ক্রিন পড়ার পরে, আর দুটোর মধ্যে অমিল হলে জেতে স্ক্রিন। ডকস যদি বলে একটা মেম্বার যোগ করুন বাটন আছে আর স্ক্রিন বলে সেটা নিষ্ক্রিয়, তাহলে উত্তর হবে নিষ্ক্রিয় বাটনটাকে নিয়েই।
– ভিত্তি করুন রেন্ডার হওয়া ইন্টারফেসকে, ডকসকে নয়। “সাধারণভাবে সত্যি” হলো সবচেয়ে দামি ধরনের ভুল।
– পাঠান কাঠামো, পিক্সেল বা কাঁচা HTML নয়: ইন্টারঅ্যাক্টিভ এলিমেন্ট, সম্পর্ক, UI-এর তথ্য, সংক্ষেপ করা কনটেন্ট।
– পেজ থিতু হলে স্ন্যাপশট নিন, আর প্রতিটি কাজের পর আবার নিন; DOM প্রতিনিয়ত বদলায়।
– ক্লায়েন্টেই ডেটা কমিয়ে আনুন। মডেল জানবে ডেটার আকার, ডেটা নয়।
– বর্ণনা নয়, দেখিয়ে দিন। এলিমেন্ট একবার দেখতে পেলে সেটা দেখানোও যায়।
ইনস্টল এখনো এক লাইনের
একটা যুক্তিসংগত দুশ্চিন্তা হলো, “রেন্ডার হওয়া ইন্টারফেস পড়ে” মানে বুঝি গভীর ইন্টিগ্রেশন। তা নয়। উইজেটটা স্রেফ একটা স্ক্রিপ্ট ট্যাগ, যা বসে আপনার আগে থেকে রেন্ডার হওয়া লেআউটে; এটি shadow DOM-এ নিজের রুট মাউন্ট করে, ব্রাউজারের ভেতর থেকেই পেজ পর্যবেক্ষণ করে, আর এর জন্য কোনো রুট অ্যানোটেশন বা কম্পোনেন্ট র্যাপার লাগে না।
<script async src="https://trybarkan.com/widget.js" data-barkan-site="site_your_key"></script>ওপরে বর্ণিত সবকিছুই ঘটে ওই স্ক্রিপ্টের ভেতরে। যে প্রোডাক্টে এটি ইনস্টল করা, তার জানারও দরকার নেই যে Barkan বলে কিছু আছে।
স্নিপেটটা ইনস্টল করুন, আপনার অ্যাপ খুলুন, আর Barkan-কে এমন কিছু জিজ্ঞেস করুন, যার উত্তর আপনার ডকস দিতে পারে না। শুরুতে $25-এর ক্রেডিট, কার্ড লাগবে না।
“বেশিরভাগ ইউজার আরেকটা উত্তর চান না। তাঁরা চান কেউ পথটা দেখিয়ে দিক, নয়তো কাজটাই করে দিক। পুরো প্রোডাক্টটা এটুকুই।”
Gabriel Lancelot
সহ-প্রতিষ্ঠাতা, Barkan
