লাভ:
- লক্ষ্য শ্রোতা এবং এআই এর সাথে উত্সের উপর ভিত্তি করে README, ডকস্ট্রিং এবং চেঞ্জলগ ড্রাফ্ট তৈরি করার ক্ষমতা
- ডকুমেন্টেশনে 'কী/কিভাবে' এবং 'কেন' স্তরগুলিকে আলাদা করার এবং একজন মানুষ হিসাবে 'কেন' যোগ করার ক্ষমতা
- ইনস্টলেশনের ধাপগুলি ব্যক্তিগতভাবে চালানোর মাধ্যমে যাচাই করা এবং নথিটিকে কোড পরিবর্তনের একটি অংশ করে
সফ্টওয়্যারের সবচেয়ে ঘন ঘন অবহেলিত কিন্তু দীর্ঘস্থায়ী অংশ হল ডকুমেন্টেশন। কোড মাস পরেও পাঠযোগ্য; যিনি এটি লিখেছেন তিনি চলে গেছেন, প্রসঙ্গটি ভুলে গেছেন এবং যা লেখা ছিল তা অবশিষ্ট রয়েছে। একটি ভাল README (পরিচয়মূলক নথি যা ব্যাখ্যা করে যে একটি প্রকল্প কী এবং এটি কীভাবে ইনস্টল এবং চালাতে হয়), ব্যাখ্যামূলক কোড মন্তব্য এবং একটি আপ-টু-ডেট API ডকুমেন্টেশন (একটি রেফারেন্স যা ব্যাখ্যা করে কিভাবে একটি ইন্টারফেস ব্যবহার করতে হয়) সরাসরি একটি দলের গতি নির্ধারণ করে। AI ডকুমেন্টেশনের বাইরে প্রচুর "লেখার ক্লান্তি" নেয় — তবে এটি একটি ফাঁদ নিয়ে আসে: AI কোড থেকে অনুমান করতে পারে এটি কী করে, কিন্তু প্রায়শই জানতে পারে না কেন এটি এমনভাবে করা হয়েছে।
এই ইউনিটে, আপনি শিখবেন কিভাবে README, কোড কমেন্ট, ডকস্ট্রিং (ফাংশন/ক্লাস প্রতি লেখা মন্তব্য ব্লক), API ডকুমেন্ট এবং AI দিয়ে চেঞ্জলগ তৈরি করতে হয়; এবং কীভাবে মানবিকভাবে ডকুমেন্টেশনের সবচেয়ে মূল্যবান অংশটি সংরক্ষণ করবেন: "কেন।"
"কি" এবং "কেন" এর মধ্যে পার্থক্য
ডকুমেন্টেশন দুটি স্তর আছে. প্রথমটি কি/কীভাবে: "এই ফাংশনটি একটি তালিকা সাজায়", "ইনস্টল করতে এই কমান্ডটি চালান"। এগুলি কোড এবং কাঠামো থেকে বের করা যেতে পারে; AI এখানে উৎকর্ষ। দ্বিতীয়ত, কেন: "কেন আমরা এই পরিষেবাটিকে সিঙ্ক্রোনাস না করে অ্যাসিঙ্ক্রোনাস করেছি", "কেন এই সীমার মান 30 সেকেন্ড", "কেন আমরা এই লাইব্রেরিটিকে অন্যের উপরে বেছে নিয়েছি"। এগুলো কোডে লেখা নেই; এটি ডিজাইনের সিদ্ধান্ত, সীমাবদ্ধতা এবং অতীতের ব্যথার ফসল।
AI "কেন" জানে না; সর্বোপরি, এটি একটি যুক্তিসঙ্গত অনুমান তৈরি করে - যা বিপজ্জনক, কারণ একটি ভুল কারণ কোনও কারণ ছাড়াই খারাপ। সুতরাং শ্রমের বিভাজন স্পষ্ট: AI "কী/কিভাবে" এর খসড়া তৈরি করে, আপনি "কেন" যোগ করেন। সবচেয়ে মূল্যবান মন্তব্য হল কোড যা বলতে পারে না তা বলে।
পরামর্শ: কোডটি স্পষ্টভাবে যা বলে তা মন্তব্যের সাথে পুনরাবৃত্তি করবেন না (যেমন i = i + 1 // i এক দ্বারা বৃদ্ধি করুন)। এআই কখনও কখনও এই ধরনের অপ্রয়োজনীয় মন্তব্য তৈরি করে; সেগুলি বাদ দিন এবং "কেন" মন্তব্যে আপনার শক্তি উৎসর্গ করুন।
ধাপে ধাপে: এআই সহ ডকুমেন্টেশন জেনারেশন
- লক্ষ্য শ্রোতা নির্দিষ্ট করুন. "একজন বিকাশকারী এইমাত্র শুরু করছে," "বাহ্যিক দল যারা এই API ব্যবহার করবে," "ভবিষ্যত আমি" — দর্শকরা ভাষা এবং গভীরতার জন্য সুর সেট করে।
- উৎস দিন। প্রম্পটে প্রাসঙ্গিক কোড, বিদ্যমান README, উদাহরণ ব্যবহার যোগ করুন। একটি আনসোর্সড ডকুমেন্ট বানোয়াট একটি আমন্ত্রণ.
- আরোপ কাঠামো। README এর জন্য স্ট্যান্ডার্ড বিভাগ (উদ্দেশ্য, ইনস্টলেশন, ব্যবহার, কনফিগারেশন, অবদান), ডকস্ট্রিংয়ের জন্য প্রকল্প বিন্যাস।
- "কেন" স্পেস চিহ্নিত করুন। AI কে এমন সিদ্ধান্তগুলি চিহ্নিত করতে বলুন যার জন্য এটি "এখানে একটি 'কেন' নোট প্রয়োজন" হিসাবে যৌক্তিকতা জানে না; তারপর আপনি ঐ শূন্যস্থান পূরণ করুন.
- যাচাই করুন। প্রকৃতপক্ষে ইনস্টলেশন পদক্ষেপগুলি চালান; নমুনা কোড চেষ্টা করুন। একটি README যে কাজ করে না তা কোন README এর চেয়ে খারাপ।
তিনটি মিনি কেস
কেস 1 — README অনবোর্ডিং ত্বরান্বিত করেছে। একটি ওপেন সোর্স টুলের README অনুপস্থিত ছিল; নতুন অবদানকারীরা গড়ে 2 ঘন্টা ইনস্টলেশনের সাথে লড়াই করেছেন। দলটি AI কে ইনস্টলেশন স্ক্রিপ্ট এবং package.json দিয়েছে এবং একটি কাঠামোগত README খসড়া তৈরি করেছে, তারপরে একটি পরিষ্কার মেশিনে পদক্ষেপগুলি চালিয়েছে এবং দুটি অনুপস্থিত নির্ভরতা যুক্ত করেছে। পরবর্তী অবদানকারীদের জন্য ইনস্টলেশন সময় গড়ে 25 মিনিটে হ্রাস পেয়েছে।
কেস 2 — তৈরি করা "কেন" ফাঁদ। একজন বিকাশকারী AI-কে একটি টাইমআউট মানের (টাইমআউট=30) পাশে একটি মন্তব্যের জন্য জিজ্ঞাসা করেছিলেন। AI একটি যুক্তিসঙ্গত কিন্তু ভুল ন্যায্যতা লিখেছেন "উচ্চ নেটওয়ার্ক লেটেন্সি সহ্য করতে"; আসল কারণটি ছিল একটি ডাউনস্ট্রিম পরিষেবার চুক্তিভিত্তিক 30-সেকেন্ডের সীমা। ভুল ব্যাখ্যা পরবর্তী ডেভেলপারকে অপ্রয়োজনীয়ভাবে মান বাড়াতে পরিচালিত করে, যার ফলে একটি ঘটনা ঘটে। পাঠ: কোডের মালিককে অবশ্যই ন্যায্যতা যাচাই করতে হবে।
কেস 3 - ডকস্ট্রিং স্ট্যান্ডার্ড স্বয়ংক্রিয় হয়ে উঠেছে। 40টি ফাংশন সহ একটি অক্জিলিয়ারী মডিউলে কোনো ডকস্ট্রিং নেই। এআইকে প্রকল্পের বিন্যাস (গুগল স্টাইল) দেওয়া হয়েছিল এবং প্রতিটি ফাংশনের জন্য প্যারামিটার, রিটার্ন এবং ব্যতিক্রম বিবরণ তৈরি করা হয়েছিল; বিকাশকারী এগুলি পর্যালোচনা করেছে এবং কয়েকটি ভুল টাইপ ঘোষণা সংশোধন করেছে৷ ডকুমেন্টিং 40টি ফাংশন প্রায় অর্ধেক দিন থেকে এক ঘন্টা নেমে গেছে।
চারটি অনুলিপিযোগ্য টেমপ্লেট
স্ট্রাকচার্ড README খসড়া:
লক্ষ্য দর্শক: {{যেমন new contributor}}. নীচের ফাইলগুলির উপর ভিত্তি করে একটি খসড়া README লিখুন৷ বিভাগ: উদ্দেশ্য, বৈশিষ্ট্য, প্রয়োজনীয়তা, ইনস্টলেশন, অপারেশন, কনফিগারেশন, পরীক্ষা, অবদান। প্রকৃত ফাইল থেকে ইনস্টলেশন/চলমান কমান্ডগুলি বের করুন; ফিটিং। আপনি নিশ্চিত নন এমন জায়গাগুলিকে "[VERIFY]" দিয়ে চিহ্নিত করুন। সূত্র: {{package.json/scripts/sample code}}
ডকস্ট্রিং/এপিআই রেফারেন্স:
এই ফাংশনগুলিতে ডকস্ট্রিং লিখুন {{প্রকল্প শৈলী: Google/NumPy/JSDoc}} বিন্যাসে: সংক্ষিপ্ত সারসংক্ষেপ, প্যারামিটার (টাইপ + অর্থ), রিটার্ন, ব্যতিক্রম থ্রো, 1টি ছোট উদাহরণ। কোডটি স্পষ্টভাবে যা বলে তা পুনরাবৃত্তি করবেন না। ডিজাইনের সিদ্ধান্তগুলিকে "কেন" হিসাবে "[কেন প্রয়োজনীয়]" হিসাবে চিহ্নিত করুন, একটি বানোয়াট যুক্তি লিখবেন না৷{{code}}
"কেন" মন্তব্যের জন্য স্থান সরান:
এই কোডে, পরবর্তী বিকাশকারী জিজ্ঞাসা করতে পারে "কেন এটি এমন?" (জাদু সংখ্যা, অস্বাভাবিক সিদ্ধান্ত, সমাধান)। প্রতিটির জন্য একটি মন্তব্য কঙ্কাল দিন, কিন্তু যুক্তি খালি ছেড়ে দিন; আমি যৌক্তিকতা পূরণ করব।{{code}}
চেঞ্জলগ/পিআর বিবৃতি:
নিচের পার্থক্য থেকে একটি {{চেঞ্জলগ এন্ট্রি / পিআর বর্ণনা}} লিখুন। বিন্যাস: কী পরিবর্তিত হয়েছে (ব্যবহারকারীর ভাষায়), কেন (ইস্যু: {{...}}), ব্রেকিং পরিবর্তন (যদি থাকে), এটি কি পরীক্ষা করা হয়েছে। লক্ষ্য দর্শকদের জন্য প্রযুক্তিগত শব্দগুচ্ছ সামঞ্জস্য করুন।{{diff}}
দুর্বল প্রম্পট / শক্তিশালী প্রম্পট
দুর্বল: "এই প্রকল্পের জন্য একটি README লিখুন।"
শক্তিশালী: "টার্গেট অডিয়েন্স: একজন ডেভেলপার এই রেপোকে প্রথমবারের মতো ক্লোন করছে। সংযুক্ত প্যাকেজ.json, docker-compose.yml এবং স্ক্রিপ্ট/ ফোল্ডারের উপর ভিত্তি করে, উদ্দেশ্য, প্রয়োজনীয়তা, ইনস্টলেশন, অপারেশন, টেস্টিং, কন্ট্রিবিউশন বিভাগ সহ একটি ড্রাফ্ট README লিখুন। সেগুলি থেকে কমান্ডগুলি এক্সট্র্যাক্ট করুন যেখানে আপনি এই ফাইলগুলিকে চিহ্নিত করবেন না; [যাচাই]।"
শক্তিশালী সংস্করণ শ্রোতা, উত্স, কাঠামো এবং "এটি তৈরি করুন, এটি চিহ্নিত করুন" নিয়ম দেয়; যাতে ডকুমেন্টটি বাস্তব ফাইলের উপর ভিত্তি করে এবং যাচাই করার স্থানগুলি স্পষ্টভাবে দৃশ্যমান হয়।
নথির ধরন
এআই ভালো করে
মানুষ যোগ/যাচাই করে
README ইনস্টলেশন
ধাপের রূপরেখা
ধাপগুলি চালান এবং নিশ্চিত করুন
ডকস্ট্রিং/এপিআই
স্ট্রাকচার, প্যারামিটার, টাইপ
সঠিক প্রকার এবং "কেন"
কোড মন্তব্য
"সে কি করছে" সারাংশ
"এটা কেন" ন্যায্যতা
চেঞ্জলগ/পিআর
প্রথম খসড়া
প্রভাব এবং নির্ভুলতা
স্থাপত্য সিদ্ধান্ত (ADR)
কঙ্কাল
বাস্তব সিদ্ধান্ত এবং আপস
ডকুমেন্টেশন রক্ষণাবেক্ষণ প্রয়োজন
একটি নথির সবচেয়ে বিপজ্জনক দিক হল যখন এটি সত্য বলে মনে হয় যদিও এটি মিথ্যা। যখন কোড পরিবর্তন হয় এবং নথি আপডেট করা হয় না, তখন এটি সক্রিয়ভাবে পাঠককে বিভ্রান্ত করে। AI আপডেট করা সহজ করে: একটি পার্থক্য জারি করুন এবং জিজ্ঞাসা করুন "এই পরিবর্তনটি নথির কোন অংশগুলিকে প্রভাবিত করে?" আপনি জিজ্ঞাসা করতে পারেন। কিন্তু এটি এমন একটি প্রক্রিয়া যা আপ-টু-ডেটনেস নিশ্চিত করে — ডকুমেন্টেশন আপডেটকে কোড পরিবর্তনের অংশ করে তুলুন (PR-এর গ্রহণযোগ্যতার মানদণ্ড)। এআই ত্বরান্বিত; দল শৃঙ্খলা তৈরি করে।
সতর্কতা: README-এ ইনস্টলেশনের ধাপগুলি যাচাই না করে প্রকাশ করবেন না। একটি "সম্ভবত কাজ" নথি একটি নতুন ডেভেলপারের প্রথম দিন নষ্ট করতে পারে এবং বিশ্বাস নষ্ট করতে পারে। পরিচ্ছন্ন পরিবেশে ধাপগুলো নিজে চালান।
সাধারণ ভুল
- AI এর সাথে মানানসই করার জন্য “কেন” পাওয়া যাচ্ছে। মিথ্যা ন্যায্যতা কোন ন্যায্যতা চেয়ে খারাপ; কোড মালিককে ডিজাইনের কারণ লিখতে হবে।
- ইনস্টলেশনের ধাপগুলি যাচাই করা হচ্ছে না। README যে কাজ করে না বিশ্বাস নষ্ট করে।
- অপ্রয়োজনীয় মন্তব্য কোড পুনরাবৃত্তি. এটি শব্দ উৎপন্ন করে, বাস্তব "কেন" ব্যাখ্যাকে অস্পষ্ট করে।
- টার্গেট শ্রোতা নির্দিষ্ট না. একটি নথি যা অস্পষ্ট কার কাছে লেখা হয়েছে তা নবজাতক বা বিশেষজ্ঞের জন্য কোন কাজে আসে না।
- প্রক্রিয়া থেকে আপডেট পৃথক করা হচ্ছে. যদি নথিটি কোডের সাথে আপডেট না করা হয় তবে এটি দ্রুত বিভ্রান্তিকর হয়ে ওঠে।
সংক্ষেপে
এআই ডকুমেন্টেশনের বাইরে অনেক যান্ত্রিক বোঝা নিয়ে যায়: দ্রুত খসড়া README, ডকস্ট্রিং, API রেফারেন্স, চেঞ্জলগ এবং PR বর্ণনা। কিন্তু এটি "কেন", যা সবচেয়ে মূল্যবান স্তর তা জানতে পারে না এবং এটি তৈরি করা বিপজ্জনক। শ্রমের বিভাজন স্পষ্ট: AI তৈরি করে "কি/কিভাবে," আপনি যোগ করেন "কেন"। শ্রোতাদের নির্দিষ্ট করুন, সংস্থানগুলি প্রদান করুন, কাঠামো আরোপ করুন, ফিট করার জন্য স্থানগুলি চিহ্নিত করুন এবং প্রতিটি ইনস্টলেশন ধাপ নিজেই চালিয়ে যাচাই করুন৷ ডকুমেন্টেশন কোড পরিবর্তন একটি অবিচ্ছেদ্য অংশ করুন.
আবেদন টাস্ক
একটি মডিউল বা ছোট প্রকল্প চয়ন করুন যার ডকুমেন্টেশন অনুপস্থিত বা পুরানো। প্রথমে "গঠিত README খসড়া" (বা ডকস্ট্রিং) টেমপ্লেট সহ AI থেকে একটি রূপরেখা তৈরি করুন; উৎস এবং লক্ষ্য দর্শক দিতে ভুলবেন না. তারপর প্রতিটি পয়েন্টের মধ্য দিয়ে যান যেখানে AI চিহ্নিত করেছে [যাচাই] বা [কেন প্রয়োজন]: আসলে সেটআপের ধাপগুলি চালান এবং আপনার নিজের জ্ঞান দিয়ে ডিজাইনটি "কেন" পূরণ করুন। কতগুলি ধাপ ঠিক করা দরকার এবং কতগুলি "কেন" আপনি যোগ করেছেন তা নোট করুন৷
চেকলিস্ট
- [ ] ডকুমেন্টেশনে, আমি "কি/কিভাবে" এবং "কেন" স্তরগুলিকে আলাদা করি৷
- [] আমি AI মেক আপ করি না "কেন", আমি নিজেই এটি যোগ করি।
- [ ] আমি প্রম্পটটি টার্গেট অডিয়েন্স এবং আসল সোর্স ফাইল দিই।
- [ ] আমি AI দ্বারা চিহ্নিত [যাচাই] পয়েন্টগুলি ব্যক্তিগতভাবে সম্পাদন করে যাচাই করি৷
- [ ] আমি অপ্রয়োজনীয় মন্তব্য মুছে ফেলি যা কোড পুনরাবৃত্তি করে।
- [ ] আমি কোড পরিবর্তনের ডকুমেন্টেশন আপডেট অংশ তৈরি করছি।