২৬ ডিসে, ২০২৫·7 মিনিট
Claude Code: ডকুমেন্টেশন ড্রিফট আটকান এবং ডকসকে কোডের সাথে সারিবদ্ধ রাখুন
Claude Code ব্যবহার করে ডকুমেন্টেশন ড্রিফট শনাক্ত ও ঠিক করুন—README, API ডকস, এবং রানবুকগুলোকে কোডের সাথে সারিবদ্ধ রাখুন ডিফ ও বিরোধ কলআউট জেনারেট করে।
Claude Code ব্যবহার করে ডকুমেন্টেশন ড্রিফট শনাক্ত ও ঠিক করুন—README, API ডকস, এবং রানবুকগুলোকে কোডের সাথে সারিবদ্ধ রাখুন ডিফ ও বিরোধ কলআউট জেনারেট করে।
ডকুমেন্টেশন ড্রিফট হলো আপনার ডকস যা বলে এবং আপনার কোড যা করে তার মধ্যে ধীর পরিবর্তন। এটা ছোট অমিল থেকে শুরু হয়, তারপর "আমরা গত মাসে এটা কাজ করেছিলাম" ধাঁচের বিভ্রান্তিতে পরিণত হয়।
বাস্তবে ড্রিফট এরকম দেখায়: README বলে একটি কমান্ডেই সার্ভিস চালবে, কিন্তু এখন একটি নতুন environment variable প্রয়োজন। API ডকস একটি ফিল্ড দেখায় যার নাম বদলে গেছে। একটি রানবুক অন-কলকে বলে "worker-a" রিস্টার্ট করতে, কিন্তু প্রক্রিয়াটি এখন দুটো সার্ভিসে ভাগ হয়ে গেছে।
ড্রিফট ভালো ইচ্ছার সাথেও ঘটে কারণ সফটওয়্যার ডকুমেন্টেশন অভ্যাসের চেয়ে দ্রুত বদলে। মানুষ চাপের মধ্যে ফিক্স শিপ করে, পুরনো উদাহরণ কপি করে, বা ধরে নেয় কেউ পরে ডকস আপডেট করবে। যখন আপনার কাছে অনেকগুলো স্থান থাকে যা "সোর্স অফ ট্রুথ" মনে হয়—README ফাইল, API রেফারেন্স, ইন্টার্নাল উইকি পেজ, টিকিট, এবং ট্রাইবাল নলেজ—তখনও ড্রিফট বাড়ে।
এর খরচগুলো বাস্তব:
লেখার ঝক্কি ঠিক করে ড্রিফট ঠিক হবে না যদি তথ্যই ভুল হয়। যেটা সাহায্য করে তা হলো ডকসকে এমন কিছু হিসেবে দেখা যা যাচাই করা যায়: সেগুলোকে বর্তমান কোড, কনফিগ, এবং বাস্তব আউটপুটের সঙ্গে তুলনা করুন, তারপর যেখানে ডকস কোনো আচরণ প্রতিশ্রুত করে কিন্তু কোড আর তা করে না সেখানে বিরোধ চিহ্নিত করুন।
ড্রিফট সাধারণত সেই সকল ডকুমেন্টগুলোতে দেখা যায় যেগুলো মানুষ "কুইক রেফারেন্স" হিসেবে ব্যবহার করে। সেগুলো একবার আপডেট হয়, তারপর কোড চলতেই থাকে। এই তিনটি থেকেই শুরু করুন কারণ সেগুলোতে স্পষ্ট প্রতিশ্রুতি থাকে যা আপনি যাচাই করতে পারেন।
READMEs তখনই ড্রিফট হয় যখন প্রতিদিনের কমান্ড বদলে যায়। একটি নতুন ফ্ল্যাগ যোগ হয়, পুরনোটি মুছে যায়, অথবা একটি environment variable রিনেইম হয়, কিন্তু সেটআপ অংশ এখনও পুরনো বাস্তবতা দেখায়। নতুন সহকর্মীরা কপি-পেস্ট করে, ত্রুটিতে পড়ে, এবং প্রকল্পটিই ভাঙা মনে করে।
সবচেয়ে খারাপ অবস্থা হলো "প্রায় ঠিক"। একটি অনুপস্থিত environment variable পুরোপুরি পুরনো README-র চেয়ে বেশি সময় নষ্ট করতে পারে, কারণ মানুষ ছোট ছোট ভ্যারিয়েশন ট্রাই করতে থাকেন পরিবর্তে ডকসটাকে প্রশ্ন করা।
API ডকস ড্রিফট হয় যখন রিকুয়েস্ট বা রেসপন্স ফিল্ড বদলে যায়। এমনকি ছোট পরিবর্তন (রিনেইম করা কীগুলো, ভিন্ন ডিফল্ট, নতুন আবশ্যক header) ক্লায়েন্ট ভেঙে দিতে পারে। প্রায়ই এন্ডপয়েন্ট তালিকা সঠিক থাকে কিন্তু উদাহরণগুলো ভুল থাকে—আর সেটাই মানুষ কপি করে ব্যবহার করে।
সাধারণ সংকেতসমূহ:
রানবুক তখনি ড্রিফট হয় যখন ডিপ্লয়, রোলব্যাক, বা অপারেশনাল ধাপ বদলে যায়। একটি পুরনো কমান্ড, ভুল সার্ভিস নাম, বা অনুপস্থিত প্রাক-শর্ত রুটিন ফিক্সকে ডাউনটাইমে বদলে দিতে পারে।
এগুলোরও থাকতে পারে "ঠিক আছে কিন্তু অসম্পূর্ণ" অবস্থা: ধাপগুলো এখনও কাজ করে, কিন্তু তারা একটি নতুন মাইগ্রেশন, ক্যাশ ক্লিয়ার, বা ফিচার ফ্ল্যাগ টগল বাদ দিয়ে দেয়। তখন প্রতিক্রিয়াকর্তারা রানবুক নিখুঁতভাবে অনুসরণ করলেও বিস্মিত হয়।
Claude Code ডকুমেন্টেশন ড্রিফটের জন্য সবচেয়ে ভাল কাজ করে যখন আপনি ডকসকে কোডের মত扱েন: একটি ছোট, রিভিউযোগ্য প্যাচ প্রস্তাব করুন এবং কারণ ব্যাখ্যা করুন। "README আপডেট করুন" বলার বদলে নির্দিষ্ট ফাইলগুলোর বিরুদ্ধে একটি ডিফ তৈরি করতে বলুন। রিভিউয়াররা স্পষ্ট আগে/পরে দেখতে পাবেন এবং অনুপযুক্ত পরিবর্তন সহজেই চিহ্নিত করতে পারবেন।
একটি ভাল ড্রিফ চেক দুইটা জিনিস উত্পাদন করে:
আপনি যখন প্রম্পট দেবেন, রিপো থেকে প্রমাণ বাধ্য করুন: ফাইল পাথ এবং রাউট, কনফিগ ভ্যালু, বা টেস্টের মত বিস্তারিত যা বর্তমান আচরণ প্রদর্শন করে।
এই প্রম্পট প্যাটার্নটি ব্যবহার করুন যাতে এটি মাটিতে থাকে:
Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.
যদি Claude বলে "API /v2 ব্যবহার করে", সেটি রাউটার, OpenAPI স্পেক, বা একটি ইন্টিগ্রেশন টেস্ট দেখিয়ে প্রমাণ দেব। যদি প্রমাণ না পায়, সেটি তা বলে দিতে হবে।
ড্রিফট সাধারণত একটি কোড পরিবর্তন থেকে শুরু হয় যা নীরবে একাধিক ডককে প্রভাবিত করে। Claude-কে প্রথমে প্রভাব স্কোপ করতে বলুন: কী পরিবর্তিত হয়েছে, কোথায় পরিবর্তিত হয়েছে, কোন ডকসগুলো সম্ভবত ভাঙছে, এবং কোন ব্যবহারকারীর ক্রিয়াগুলো প্রভাবিত হচ্ছে।
উদাহরণ: আপনি একটি environment variable API_KEY থেকে SERVICE_TOKEN এ রিনেইম করেছেন। একটি উপযোগী রিপোর্ট পুরনো নামটি যেখানে কোথায় আছে সব জায়গা (README সেটআপ, API উদাহরণ, রানবুক সিক্রেটস সেকশন) খুঁজে বের করে, তারপর একটি টাইট ডিফ তৈরি করে যা ওই লাইনগুলো এবং যেখানে উদাহরণ কমান্ডগুলো বাইতে ব্যর্থ হবে সেগুলোই আপডেট করে।
যদি আপনি একটি মডেলকে "সব ডকস" দেখান কোনো নিয়ম ছাড়া, প্রায়ই আপনি এমন রিরাইট পাবেন যা এখনও ভুল তথ্য ধরে রাখে। একটি সাধারণ ওয়ার্কফ্লো পরিবর্তনগুলো ছোট, পুনরাবৃত্তিমূলক এবং রিভিউযোগ্য রাখে।
একটি ডক সেট দিয়ে শুরু করুন: README, API রেফারেন্স, অথবা একটি ব্যবহারশীল রানবুক। একটার উপর এন্ড-টু-এন্ড ঠিক করা আপনাকে শেখাবে কোন সিগন্যালগুলো বিশ্বাসযোগ্য তারপর বড়ভাবে বাড়ানোর আগে।
সরল শব্দে লিখে রাখুন যে সেই ডক সেটের জন্য তথ্য কোথা থেকে আসবে:
একবার আপনি সেই সোর্সগুলো নাম দিলেন, প্রম্পটগুলো স্পষ্ট হবে: "README-কে বর্তমান CLI আউটপুট ও কনফিগ ডিফল্টের সঙ্গে তুলনা করুন, তারপর একটি প্যাচ জেনারেট করুন।"
প্রথম চালানোর আগে আউটপুট ফরম্যাটে সম্মতি করুন। মিক্স করা ফরম্যাট পরিবর্তন ও কারণ বোঝার আগ্রহ কমায়।
সরল নিয়মগুলো:
একটি ব্যবহারিক অভ্যাস: প্রতিটি ডক PR-এ একটি ছোট নোট যোগ করুন যেমন "Source of truth checked: routes + tests" যাতে রিভিউয়াররা জানে কী তুলনা করা হয়েছিল। এটি ডক আপডেটগুলোকে "ভালো লাগছে" থেকে "কোন কিছু যাচাই করা হয়েছে" তে পরিণত করে।
প্রতিটি কোড পরিবর্তনকে একটি ছোট ডকস তদন্ত হিসেবে বিবেচনা করুন। উদ্দেশ্য হলো বিরোধগুলো শিগগির ধরা এবং এমন একটি ন্যূনতম প্যাচ তৈরি করা যা রিভিউয়ার ভরসা করতে পারে।
শুরুতে ঠিক ফাইলগুলো এবং একটি পরিষ্কার ড্রিফট প্রশ্ন নির্বাচন করুন। উদাহরণ: "আমরা কি কোনো environment variable, CLI ফ্ল্যাগ, HTTP রুট, বা এরর কোড বদলিয়েছি যা ডকস এখনও উল্লেখ করে?" নির্দিষ্ট থাকা মডেলকে পুরো অংশ রিরাইট করা থেকে আটকায়।
এরপর Claude Code-কে প্রথমে কোড থেকে কঠোর তথ্য বের করতে বলুন। এটি কেবল কনক্রিট আইটেমগুলো তালিকাভুক্ত করবে: ব্যবহারকারীরা চালানো কমান্ড, এন্ডপয়েন্ট ও মেথড, রিকুয়েস্ট ও রেসপন্স ফিল্ড, কনফিগ কী, আবশ্যক environment ভ্যারিয়েবল, এবং স্ক্রিপ্ট বা কনফিগ দ্বারা রেফার করা অপারেশনাল ধাপগুলো। যদি কিছু কোডে না পাওয়া যায়, সেটি "not found" বলে দিতে হবে অনুমান না করে।
তারপর একটি সরল তুলনা টেবিল চাইুন: ডক দাবি, কোড কি দেখায়, এবং স্থিতি (match, mismatch, missing, unclear)। এটি আলোচনা মাটিতে রাখে।
এরপর একটি ন্যূনতম ইউনিফাইড ডিফ অনুরোধ করুন: কেবল অমিল মিট করার জন্য প্রয়োজনীয় লাইনগুলো বদলাতে বলুন, ডকসের বিদ্যমান স্টাইল রাখুন, এবং এমন প্রতিশ্রুতি যোগ করা এড়ান যা কোড সমর্থন করে না।
শেষে একটি সংক্ষিপ্ত রিভিউয়ার সারাংশ দিন: কী বদলেছে, কেন বদলেছে, এবং কি পরীক্ষা করে দেখবে (যেমন একটি রিনেইম করা environment variable বা একটি নতুন আবশ্যক হেডার)।
API ডকস তখনই ড্রিফট হয় যখন কোড নীরবে বদলে: একটি রুট রিনেইম হয়, একটি ফিল্ড আবশ্যক হয়, বা একটি এরর শেইপ বদলে যায়। ফলাফল হলো ভাঙা ক্লায়েন্ট ইন্টেগ্রেশন এবং অপচয় করা ডিবাগিং টাইম।
Claude Code ডকুমেন্টেশন ড্রিফটের সঙ্গে কাজ করার সময় কাজটি হলো রিপো থেকে API কী করে তা প্রমাণ করা, তারপর ডকসের অমিলগুলোকে নির্দেশ করা। রাউটিং ও হ্যান্ডলার থেকে একটি ইনভেন্টরি বের করাতে বলুন (পাথ, মেথড, রিকুয়েস্ট ও রেসপন্স মডেল) এবং সেটি API রেফারেন্সের দাবির সঙ্গে তুলনা করান।
মানুষ যা কপি-পেস্ট করে সেটা উপর ফোকাস করুন: curl কমান্ড, হেডার, স্যাম্পল পে-লোড, স্ট্যাটাস কোড, এবং ফিল্ড নাম। একক প্রম্পটে এটাকে পরীক্ষা করতে বলুন:
যখন এটি অমিল খুঁজে পায়, কেবলমাত্র সেই ডিফগুলো গ্রহণ করুন যেখানে এটি কোড থেকে প্রমাণ (নির্দিষ্ট রুট সংজ্ঞা, হ্যান্ডলার আচরণ, বা স্কিমা) উদ্ধৃত করতে পারে। এতে প্যাচগুলো ছোট ও রিভিউযোগ্য থাকে।
উদাহরণ: কোড এখন POST /widgets এ 201 রিটার্ন করে এবং একটি আবশ্যক name ফিল্ড যোগ করেছে। ডকস এখনও 200 দেখায় এবং name অনুপস্থিত। একটি ভাল আউটপুট উভয় বিরোধকে কল করে এবং কেবলমাত্র ঐ এন্ডপয়েন্টের স্ট্যাটাস কোড ও উদাহরণ JSON আপডেট করে, বাকি কিছু অছুঁত রেখে।
রানবুক সবচেয়ে ব্যয়বহুলভাবে ব্যর্থ হয়: সেগুলো সম্পূর্ণ মনে হয়, কিন্তু ধাপগুলো আর সিস্টেম যে করে তা মেলে না। একটি ছোট পরিবর্তন যেমন একটি রিনেইম করা environment variable বা একটি নতুন ডিপ্লয় কমান্ড ইনসিডেন্ট দীর্ঘ করে দিতে পারে কারণ প্রতিক্রিয়াকারীরা নির্দেশনা অনুসরণ করে যা কাজ করে না।
রানবুকটিকে কোডের মত扱ুন: বর্তমান রিপো বিরুদ্ধে একটি ডিফ চান এবং বিরোধ কলআউট বাধ্য করুন। সেটি সিস্টেম এখন কি ব্যবহার করে তার সাথে তুলনা করুন: স্ক্রিপ্ট, কনফিগ ডিফল্ট, এবং আপনার বর্তমান টুলিং।
শব্দগুলো যেখানে সবচেয়ে বেশি থ্রাশ করে সেগুলোতে ফোকাস করুন:
এছাড়া দ্রুত প্রি-চেক ও প্রত্যাশিত আউটপুট যোগ করুন যাতে প্রতিক্রিয়াকারীরা জানে তারা সঠিক পথে আছে কি না। "এটা কাজ করে তা যাচাই করুন" যথেষ্ট নয়; নির্দিষ্ট সিগন্যাল দিন (একটি স্ট্যাটাস লাইন, একটি ভার্সন স্ট্রিং, বা একটি হেলথ চেক রেসপন্স)।
যদি আপনি Koder.ai তে প্ল্যাটফর্মের মতো প্ল্যাটফর্মে অ্যাপ বিল্ড ও ডিপ্লয় করেন, এটি আরও গুরুত্বপূর্ণ কারণ স্ন্যাপশট ও রোলব্যাক শুধুমাত্র তখনই উপকারী যখন রানবুক সঠিক অ্যাকশন নাম করে এবং বর্তমান রিকভারি পাথ প্রতিফলিত করে।
ডকসকে "ভালো prose" হিসেবে ধারণা করা থেকে দ্রুত ড্রিফট সৃষ্টি হয়। ডকস শুরুতেই ভুল দাবির সেট।
একটি সাধারণ ভুল হল প্রথমে রিরাইট চাওয়া। আপনি যদি বিরোধ যাচাই না করে সোজা রিরাইট করেন, তাহলে মসৃণ লেখা পেয়ে গেলেও তা এখনও ভুল আচরণ বর্ণনা করতে পারে। সর্বদা প্রথমে জিজ্ঞেস করুন: ডকস কী দাবি করে, কোড কী করছে, এবং কোথায় তারা ভিন্ন।
আরেকটি ভুল হচ্ছে মডেলকে অনুমান করতে দেয়া। যদি কোনো আচরণ কোড, টেস্ট, বা কনফিগে দৃশ্যমান না হয়, সেটিকে অজানা হিসেবে ধরা উচিত। "সম্ভবত" হল কীভাবে README-তে প্রতিশ্রুতি তৈরী হয় এবং রানবুকগুলিকে কল্পকাহিনীতে পরিণত করে।
এগুলো প্রতিদিনের আপডেটে প্রচুর দেখা যায়:
একটি হ্যান্ডলার 401 থেকে 403 রিটার্ন করা শুরু করে আর হেডার নাম X-Token থেকে Authorization এ যায়। আপনি যদি কেবল অথ সেকশন রিরাইট করেন, আপনি হয়ত মিস করবেন যে API ডকসের উদাহরণ এখনও পুরনো হেডার দেখায়, এবং রানবুক এখনও অন-কলকে 401 স্পাইক দেখতে বলে।
ডিফ জেনারেট করলে একটি ছোট সিদ্ধান্ত লাইন যোগ করুন যেমন: "অথ ফেইলিউর এখন 403 রিটার্ন করে যাতে invalid বনাম missing credentials আলাদা করা যায়।" এটি পরবর্তী ব্যক্তিকে ডকসকে পুরনো আচরণে ফেরানোর আগেই বাধা দেবে।
প্রতিটি ডক আপডেটকে একটি ছোট অডিট হিসেবে দেখুন। লক্ষ্যটি হলো পরের সপ্তাহে কেউ নির্দেশনা অনুসরণ করলে কম অবাক হওয়া।
মার্জের আগে README, API ডকস, এবং রানবুক থেকে প্রতিটি কনক্রিট দাবিকে এক এক করে যাচাই করুন:
একই ডকে যদি দুই বা ততোধিক অজানা দাবি পান, মার্জ থামান। অথবা প্রমাণ যোগ করুন (ফাইলপাথ ও ফাংশন নাম) অথবা ডকসকে এমন জিনিস পর্যন্ত ছাঁটুন যা নিশ্চিত।
একটি ছোট দল অথ আপডেট করে: পূর্বে X-API-Key এপিআই কী পাঠাত, এখন ক্লায়েন্টরা Authorization: Bearer <token> পাঠাবে। কোড শিপ হয়, টেস্ট পাস করে, দল অগ্রসর হয়।
দুই দিন পরে, একটি নতুন ডেভেলপার README অনুসরণ করে। সেটি এখনও বলে "set X-API-Key in your environment" এবং পুরনো হেডার সহ একটি curl উদাহরণ দেখায়। তারা লোকাল রান পেতে পারে না এবং সার্ভিস ডাউন মনে করে।
এদিকে, API ডকসও স্টেল। সেগুলো পুরনো হেডার বর্ণনা করে এবং এখনও user_id নামক একটি রেসপন্স ফিল্ড দেখায়, যদিও API এখন userId ফেরত দেয়। লেখায় কিছুই ভুল নেই, কিন্তু এটি কোডের সঙ্গে বিরোধ করে, ফলে পাঠকরা ভুল জিনিস কপি করে নেয়।
তারপর একটি ইনসিডেন্ট আসে। অন-কল রানবুকের ধাপ "rotate the API key and restart workers" অনুসরণ করে। এটি সাহায্য করে না কারণ প্রকৃত সমস্যা টোকেন যাচাই সংক্রান্ত কনফিগ পরিবর্তন। রানবুক ২০ মিনিটের জন্য সঠিক দিক দেখায় না।
এখানেই Claude Code ডকুমেন্টেশন ড্রিফট কাজে লাগে যখন এটি ডিফ ও বিরোধ কলআউট উৎপন্ন করে, পুরো রিরাইট না করে। আপনি এটাকে বলতে পারেন auth middleware ও রুট হ্যান্ডলারকে README স্নিপেট, API উদাহরণ, এবং রানবুক ধাপগুলোর সঙ্গে তুলনা করতে, এবং তারপর ন্যূনতম প্যাচ প্রস্তাব করতে:
- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>
- { "user_id": "..." }
+ { "userId": "..." }
গুরুত্বপূর্ণ অংশ হলো এটি মিসম্যাচগুলোকে ফ্ল্যাগ করে, নির্দিষ্ট জায়গাগুলোকে নির্দেশ করে, এবং কেবলমাত্র রিপো প্রমাণ করে যে যেগুলো পুরনো সেগুলোই বদলে।
ডকুমেন্টেশন তখনই ঠিক থাকে যখন তা যাচাই করা বিরক্তিকর কিন্তু পুনরাবৃত্তিমূলক হয়ে ওঠে। এমন একটি ক্যাডেন্স বাছুন যা আপনার পরিবর্তনের ঝুঁকির সঙ্গে মানিয়ে নেয়। দ্রুত গতির কোডের জন্য, প্রতিটি PR-এ এটি চালান। স্থিতিশীল সার্ভিসের জন্য, একটি সাপ্তাহিক সুইপ ও রিলিজ-পূর্ব চেক প্রায়ই যথেষ্ট।
ডকুমেন্টেশন ড্রিফটকে একটি টেস্ট ফেলিওয়ারের মত扱ুন, লেখার কাজ নয়। Claude Code ব্যবহার করে একটি ছোট ডিফ এবং একটি সংক্ষিপ্ত বিরোধ তালিকা জেনারেট করুন, তারপর ডকসকে সত্য করে তোলার জন্য সবচেয়ে ছোট জিনিস ঠিক করুন।
একটি লাইটওয়েট রুটিন:
এসব ডিফ সারাংশগুলো পরে খুঁজে পাওয়াটা সহজ করুন। একটি সংক্ষিপ্ত নোট যেমন "Docs updated to match new /v2 endpoint, removed deprecated header, updated example response" মাস পরে কাউকে বলে দেয় কেন একটি ডক বদলানো হয়েছিল।
ডকসেও "স্ন্যাপশট ও রোলব্যাক" চিন্তাকে প্রয়োগ করুন। যদি একটি নির্দেশ অনিশ্চিত হয়, এক জায়গায় তা বদলান, দ্রুত যাচাই করুন, তারপর নিশ্চিত সংস্করণটি অন্য জায়গায় কপি করুন।
আপনি যদি দ্রুত তৈরি করেন, তাহলে Koder.ai (koder.ai) তে অ্যাপ ও তার প্রথম ডকস একসঙ্গে জেনারেট করা সাহায্য করতে পারে, তারপর সোর্স কোড এক্সপোর্ট করে আপনার স্বাভাবিক রিভিউ ওয়ার্কফ্লোতে পরিবর্তনগুলো রাখুন। লক্ষ্য নিখুঁত লেখাই নয়—লক্ষ্য হলো মানুষ যা করে (কমান্ড, এন্ডপয়েন্ট, ধাপ) তা কোডের সঙ্গে মিল রাখা।
ডকুমেন্টেশন ড্রিফট হলো যখন আপনার ডকস ধীরে ধীরে কোডের বাস্তব আচরণের সঙ্গে মিল হারিয়ে ফেলে। সাধারণত এটা ছোট ছোট পরিবর্তন দিয়ে শুরু হয় (একটি রিনেইম করা env var, একটি নতুন আবশ্যক ফিল্ড, একটি ভিন্ন স্ট্যাটাস কোড) যেগুলো README, API উদাহরণ, অথবা রানবুকগুলোতে প্রতিফলিত হয় না।
এটি ঘটে কারণ কোড চাপের মধ্যে দ্রুত বদলানো হয় কিন্তু ডকসগুলোর জন্য সেই একই শৃঙ্খলা থাকে না।
সাধারণ কারণগুলো:
সেগুলো হচ্ছে যেগুলো মানুষ বাস্তবে চালায়, কেবল সুন্দর-থাকা ডকস নয়। সহজতর অগ্রাধিকার:
এগুলো আগে ঠিক করলে সবচেয়ে বড় ধরনের ব্যর্থতা দূর হয়।
কারণ মসৃণ করে লেখা এখনও ভুল থাকতে পারে। ড্রিফট আসলে ভুল দাবির ব্যাপার।
একটি ভাল পদ্ধতি হলো ডকসকে টেস্টযোগ্য বিবৃতি হিসেবে দেখা: “এই কমান্ড চালান”, “এই এন্ডপয়েন্ট কল করুন”, “এই ভ্যারিয়েবল সেট করুন” — তারপর সেগুলোকে বর্তমান রিপো, কনফিগ, এবং বাস্তব আউটপুটের সঙ্গে যাচাই করা।
দুইটি আউটপুট চাওয়ার জন্য বলুন:
এছাড়া বাধ্য করুন: যদি রিপোতে প্রমাণ না মেলে, এমন হলে "not found" বলে জানাবে এবং অনুমান করবে না।
কারণ ডিফ রিভিউয়ারদের দ্রুত যাচাই করতে দেয়। একটি ডিফ ঠিক কী বদলেছে সেটা দেখায়, এবং এমন রিরাইটকে কম প্রচলিত করে যা নতুন প্রতিশ্রুতি যোগ করতে পারে।
একটি ভালো ডিফ ডিফল্ট: সম্ভব হলে একটা ফাইলে এক ডিফ, প্রতিটি পরিবর্তনের জন্য রিপো প্রমাণের সঙ্গে এক বাক্য কারণ।
চাইলে প্রমাণ দাবী করুন। ব্যবহারিক নিয়মগুলো:
লোকালভাবে মানুষ কপি-পেস্ট করে যা তারা ব্যবহার করে, তাই এগুলো পরীক্ষা করুন:
এন্ডপয়েন্ট তালিকা সঠিক হলেও উদাহরণগুলো ভুল থাকলে ব্যবহারকারীরা ব্যর্থ হয়—তাই উদাহরণগুলোকে উচ্চ অগ্রাধিকার দিন।
রানবুক তখনই ব্যর্থ হয় যখন অপারেশনাল বাস্তবতা বদলে যায়।
উচ্চ-প্রভাব পরীক্ষা:
যদি রেসপন্ডাররা অগ্রগতি যাচাই করতে না পারে, তখন তারা ইনসিডেন্টে সময় নষ্ট করবে।
একটি সাধারণ "সোর্স অফ ট্রুথ" নিয়ম প্রতিটি ডক টাইপের জন্য:
তারপর এটি ওয়ার্কফ্লোতে বেক করুন: PR-এ প্রভাবিত ডকগুলিতে ড্রিফট চেক চালান, এবং এডিটগুলো ছোট ও রিভিউযোগ্য রাখুন।