فائدہ:
- AI کے ساتھ ہدف کے سامعین اور ذریعہ کی بنیاد پر README، docstring اور چینج لاگ ڈرافٹ تیار کرنے کی صلاحیت
- دستاویزات میں 'کیا/کیسے' اور 'کیوں' تہوں کو الگ کرنے اور بطور انسان 'کیوں' شامل کرنے کی صلاحیت
- تنصیب کے مراحل کو ذاتی طور پر چلا کر اور دستاویز کو کوڈ کی تبدیلی کا حصہ بنا کر ان کی تصدیق کرنا
سافٹ ویئر کا سب سے زیادہ نظر انداز کیا جاتا ہے لیکن سب سے زیادہ دیرپا حصہ دستاویزات ہے۔ کوڈ مہینوں کے بعد بھی پڑھنے کے قابل ہے۔ جس نے لکھا تھا وہ چلا گیا، سیاق و سباق بھول گیا، اور صرف وہی رہ گیا جو لکھا تھا۔ ایک اچھی README (تعاشی دستاویز جو یہ بتاتی ہے کہ پروجیکٹ کیا ہے اور اسے کیسے انسٹال کیا جائے اور اسے کیسے چلایا جائے)، وضاحتی کوڈ کے تبصرے اور ایک تازہ ترین API دستاویزات (ایک حوالہ جو کہ انٹرفیس کو استعمال کرنے کا طریقہ بتاتا ہے) براہ راست ٹیم کی رفتار کا تعین کرتا ہے۔ AI دستاویزات سے بہت زیادہ "لکھنے کی تھکاوٹ" لیتا ہے - لیکن یہ ایک جال کے ساتھ آتا ہے: AI کوڈ سے اندازہ لگا سکتا ہے کہ یہ کیا کرتا ہے، لیکن اکثر یہ نہیں جان سکتا کہ ایسا کیوں کیا گیا ہے۔
اس یونٹ میں، آپ سیکھیں گے کہ README، کوڈ کمنٹ، docstring (فی فنکشن/کلاس لکھا ہوا تبصرہ بلاک)، API دستاویز اور AI کے ساتھ چینج لاگ کیسے تیار کیا جاتا ہے۔ اور دستاویزات کے سب سے قیمتی حصے کو انسانی طور پر کیسے محفوظ کیا جائے: "کیوں۔"
"کیا" اور "کیوں" کے درمیان فرق
دستاویزات کی دو پرتیں ہیں۔ پہلا یہ ہے کہ کیا/کیسے: "یہ فنکشن ایک فہرست کو ترتیب دیتا ہے"، "انسٹال کرنے کے لیے اس کمانڈ کو چلائیں"۔ یہ کوڈ اور ساخت سے نکالا جا سکتا ہے؛ AI یہاں بہترین ہے۔ دوم، کیوں: "ہم نے اس سروس کو ہم وقت سازی کے بجائے متضاد کیوں بنایا"، "اس حد کی قدر 30 سیکنڈ کیوں ہے"، "ہم نے اس لائبریری کو دوسری جگہ کیوں منتخب کیا"۔ یہ کوڈ میں نہیں لکھے گئے ہیں۔ یہ ڈیزائن کے فیصلوں، رکاوٹوں اور ماضی کے درد کی پیداوار ہے۔
AI نہیں جانتا "کیوں"؛ بہترین طور پر، یہ ایک معقول اندازہ لگاتا ہے - جو خطرناک ہے، کیونکہ ایک غلط وجہ بغیر کسی وجہ سے بدتر ہوتی ہے۔ لہذا محنت کی تقسیم واضح ہے: AI "کیا/کیسے" کا مسودہ تیار کرتا ہے، آپ "کیوں" شامل کرتے ہیں۔ سب سے قیمتی تبصرہ وہ ہے جو کہتا ہے کہ کوڈ کیا نہیں کہہ سکتا۔
مشورہ: کوڈ خود جو واضح طور پر کہتا ہے اسے تبصرے کے ساتھ نہ دہرائیں (جیسے i = i + 1 // i کو ایک کرکے بڑھا دیں)۔ AI بعض اوقات ایسے بے کار تبصرے پیدا کرتا ہے۔ انہیں ختم کریں اور اپنی توانائی "کیوں" تبصروں کے لیے وقف کریں۔
مرحلہ وار: AI کے ساتھ دستاویزی تخلیق
- ہدف والے سامعین کی وضاحت کریں۔ "ایک ڈویلپر ابھی شروع ہو رہا ہے،" "بیرونی ٹیم جو اس API کو استعمال کرے گی،" "مستقبل میں" — سامعین زبان اور گہرائی کے لیے لہجے کا تعین کرتے ہیں۔
- ماخذ بتائیں۔ متعلقہ کوڈ، موجودہ README، مثال کے استعمال کو پرامپٹ میں شامل کریں۔ ایک غیر منبع دستاویز من گھڑت کی دعوت ہے۔
- مسلط ڈھانچہ۔ README کے لیے معیاری حصے (مقصد، تنصیب، استعمال، ترتیب، شراکت)، دستاویز کے لیے پروجیکٹ کی شکل۔
- "کیوں" خالی جگہوں کو نشان زد کریں۔ AI سے ان فیصلوں کو نشان زد کرنے کے لیے کہے جن کے لیے وہ عقلیت کو نہیں جانتا کیونکہ "یہاں 'کیوں' نوٹ کی ضرورت ہے"؛ پھر آپ ان خالی جگہوں کو پُر کریں۔
- تصدیق کریں۔ اصل میں تنصیب کے اقدامات کو چلائیں؛ نمونہ کوڈ کی کوشش کریں. ایک README جو کام نہیں کرتا ہے وہ کسی بھی README سے بدتر ہے۔
تین چھوٹے کیسز
کیس 1 - README نے آن بورڈنگ کو تیز کیا۔ ایک اوپن سورس ٹول کا README غائب تھا۔ نئے شراکت داروں نے اوسطاً 2 گھنٹے تک تنصیب کے ساتھ جدوجہد کی۔ ٹیم نے AI کو انسٹالیشن اسکرپٹس اور package.json دیا اور ایک سٹرکچرڈ README کا مسودہ تیار کیا، پھر خود ہی ایک صاف مشین پر قدم چلائے اور دو گمشدہ انحصار کو شامل کیا۔ بعد کے شراکت داروں کے لیے تنصیب کا وقت اوسطاً 25 منٹ تک کم ہو گیا۔
کیس 2 - بنایا ہوا "کیوں" کا جال۔ ایک ڈویلپر نے AI سے ٹائم آؤٹ ویلیو (ٹائم آؤٹ = 30) کے آگے ایک تبصرہ طلب کیا۔ AI نے "اعلی نیٹ ورک کی تاخیر کو برداشت کرنے کے لیے" ایک معقول لیکن غلط جواز لکھا۔ اصل وجہ ایک ڈاون اسٹریم سروس کی معاہدہ 30 سیکنڈ کی حد تھی۔ غلط تشریح نے بعد میں آنے والے ایک ڈویلپر کو غیر ضروری طور پر قیمت میں اضافہ کیا، جس سے ایک واقعہ پیش آیا۔ سبق: کوڈ کے مالک کو جواز کی تصدیق کرنی چاہیے۔
کیس 3 - ڈاکسٹرنگ کا معیار خودکار ہو گیا ہے۔ 40 فنکشنز کے ساتھ ایک معاون ماڈیول میں کوئی دستاویز نہیں تھی۔ AI کو پروجیکٹ فارمیٹ (گوگل اسٹائل) دیا گیا تھا اور ہر فنکشن کے لیے پیرامیٹر، ریٹرن اور استثناء کی تفصیل تیار کی گئی تھی۔ ڈویلپر نے ان کا جائزہ لیا اور کچھ غلط قسم کے اعلانات کو ٹھیک کیا۔ 40 فنکشنز کی دستاویز کرنا تقریباً آدھے دن سے گھٹ کر ایک گھنٹے تک رہ گیا۔
چار کاپی ایبل ٹیمپلیٹس
سٹرکچرڈ README ڈرافٹ:
ہدف کے سامعین: {{مثال کے طور پر new contributor}}. نیچے دی گئی فائلوں کی بنیاد پر README کا مسودہ لکھیں۔ حصے: مقصد، خصوصیات، تقاضے، تنصیب، آپریشن، ترتیب، جانچ، شراکت۔ اصل فائلوں سے انسٹالیشن/رننگ کمانڈز نکالیں۔ فٹنگ ان جگہوں کو نشان زد کریں جن کے بارے میں آپ کو یقین نہیں ہے "[VERIFY]"۔ ماخذ: {{package.json/scripts/sample code}}
Docstring/API حوالہ:
ان فنکشنز کے لیے docstring {{project style: Google/NumPy/JSDoc}} فارمیٹ میں لکھیں: مختصر خلاصہ، پیرامیٹرز (قسم + معنی)، واپسی، مستثنیات پھینکے گئے، 1 مختصر مثال۔ جو کوڈ واضح طور پر کہتا ہے اسے نہ دہرائیں۔ ڈیزائن کے فیصلوں کو نشان زد کریں جن کے لیے "کیوں" کی ضرورت ہوتی ہے بطور "[WHY NECESSARY]"، کوئی من گھڑت جواز نہ لکھیں۔{{code}}
"کیوں" تبصرہ کے لیے خالی جگہیں ہٹائیں:
اس کوڈ میں، اگلا ڈویلپر پوچھ سکتا ہے "ایسا کیوں ہے؟" (جادو کی تعداد، غیر معمولی فیصلے، حل)۔ ہر ایک کے لیے ایک تبصرہ SKELETON دیں، لیکن عقلیت کو خالی چھوڑ دیں۔ میں جواز بھروں گا۔{{code}}
چینج لاگ/پی آر بیان:
نیچے دیے گئے فرق سے ایک {{changelog entry / PR description}} لکھیں۔ فارمیٹ: کیا تبدیل ہوا (صارف کی زبان میں)، کیوں (مسئلہ: {{...}})، بریکنگ تبدیلی (اگر کوئی ہے)، کیا اس کا تجربہ کیا گیا ہے۔ ہدف والے سامعین کے لیے تکنیکی اصطلاح کو ایڈجسٹ کریں۔{{diff}}
کمزور فوری / مضبوط اشارہ
کمزور: "اس پروجیکٹ کے لیے ایک README لکھیں۔"
مضبوط: "اہدافی سامعین: ایک ڈویلپر پہلی بار اس ریپو کی کلوننگ کر رہا ہے۔ منسلک پیکیج.json، docker-compose.yml اور اسکرپٹس/ فولڈر کی بنیاد پر، مقصد، تقاضے، انسٹالیشن، آپریشن، ٹیسٹنگ، کنٹریبیوشن سیکشنز کے ساتھ ایک ڈرافٹ README لکھیں۔ ان فائلوں سے کمانڈ نکالیں جہاں آپ کو نشان زد نہیں کیا گیا ہے، اس بات کو یقینی بنائیں [تصدیق کریں]۔"
مضبوط ورژن سامعین کو، ذریعہ، ساخت، اور "اسے بنائیں، نشان زد کریں" کا اصول دیتا ہے۔ تاکہ دستاویز اصلی فائلوں پر مبنی ہو اور جن جگہوں کی تصدیق کی جائے وہ واضح طور پر نظر آ سکیں۔
دستاویز کی قسم
AI اچھا کام کرتا ہے۔
انسانی اضافہ/تصدیق کرتا ہے۔
README انسٹالیشن
قدم کا خاکہ
اقدامات کو چلائیں اور تصدیق کریں۔
Docstring/API
ساخت، پیرامیٹر، قسم
صحیح قسم اور "کیوں"
کوڈ تبصرہ
"وہ کیا کر رہا ہے" کا خلاصہ
"یہ کیوں" جواز ہے۔
چینج لاگ/پی آر
پہلا مسودہ
اثر اور درستگی
تعمیراتی فیصلہ (ADR)
کنکال
حقیقی فیصلے اور سمجھوتے۔
دستاویزات کی بحالی کی ضرورت ہے۔
کسی دستاویز کا سب سے خطرناک پہلو وہ ہوتا ہے جب یہ غلط ہونے کے باوجود سچ دکھائی دیتی ہے۔ جب کوڈ تبدیل ہوتا ہے اور دستاویز کو اپ ڈیٹ نہیں کیا جاتا ہے، تو یہ قاری کو فعال طور پر گمراہ کرتا ہے۔ AI اپ ڈیٹ کرنا آسان بناتا ہے: ایک فرق جاری کریں اور پوچھیں "دستاویز کے کن حصوں پر یہ تبدیلی اثر انداز ہوتی ہے؟" آپ پوچھ سکتے ہیں۔ لیکن یہ وہ عمل ہے جو اپ ٹو ڈیٹ کو یقینی بناتا ہے — دستاویزی اپ ڈیٹ کو کوڈ کی تبدیلی کا حصہ بنائیں (PR کی قبولیت کا معیار)۔ AI تیز کرتا ہے؛ ٹیم نظم و ضبط پیدا کرتی ہے۔
احتیاط: README میں تنصیب کے مراحل کی تصدیق کیے بغیر شائع نہ کریں۔ ایک "شاید کام" کی دستاویز نئے ڈویلپر کے پہلے دن کو برباد کر سکتی ہے اور اعتماد کو ختم کر سکتی ہے۔ صاف ستھرے ماحول میں قدم خود چلائیں۔
عام غلطیاں
- AI میں فٹ ہونے کے لیے "کیوں" حاصل کرنا۔ جھوٹا جواز بغیر جواز سے بدتر ہے۔ کوڈ کے مالک کو ڈیزائن کی وجہ لکھنی چاہیے۔
- تنصیب کے مراحل کی تصدیق نہیں کرنا۔ README جو کام نہیں کرتا اعتماد کو ختم کرتا ہے۔
- کوڈ کو دہراتے ہوئے غیر ضروری تبصرہ۔ یہ شور پیدا کرتا ہے، حقیقی "کیوں" کی تشریحات کو دھندلا دیتا ہے۔
- ہدف والے سامعین کی وضاحت نہیں کرنا۔ ایک دستاویز جو واضح نہ ہو کہ یہ کس کے لیے لکھی گئی ہے، نوسکھئیے یا ماہر کے لیے کوئی فائدہ نہیں ہے۔
- اپ ڈیٹ کو عمل سے الگ کرنا۔ اگر دستاویز کو کوڈ کے ساتھ اپ ڈیٹ نہیں کیا جاتا ہے تو یہ تیزی سے گمراہ کن ہو جاتا ہے۔
خلاصہ میں
AI دستاویزات سے زیادہ مکینیکل بوجھ اٹھاتا ہے: فوری ڈرافٹ README، docstring، API حوالہ، چینج لاگ اور PR کی تفصیل۔ لیکن یہ "کیوں" کو نہیں جان سکتا، جو کہ سب سے قیمتی تہہ ہے، اور اسے بنانا خطرناک ہے۔ محنت کی تقسیم واضح ہے: AI "کیا/کیسے" پیدا کرتا ہے، آپ "کیوں" شامل کرتے ہیں۔ سامعین کی وضاحت کریں، وسائل فراہم کریں، ڈھانچہ لگائیں، فٹ ہونے کے لیے جگہوں کو نشان زد کریں، اور تنصیب کے ہر مرحلے کو خود چلا کر اس کی تصدیق کریں۔ دستاویزات کو کوڈ کی تبدیلی کا ایک لازمی حصہ بنائیں۔
درخواست کا کام
ایک ماڈیول یا چھوٹا پروجیکٹ منتخب کریں جس کی دستاویزات غائب یا پرانی ہوں۔ پہلے AI سے ایک خاکہ تیار کریں جس میں "سٹرکچرڈ README ڈرافٹ" (یا docstring) ٹیمپلیٹ؛ ذریعہ اور ہدف کے سامعین کو یقینی بنائیں۔ پھر ہر اس مقام پر جائیں جہاں AI نے نشان زد کیا ہو [Verify] یا [WHY NEEDED]: اصل میں سیٹ اپ کے مراحل کو چلائیں اور اپنے علم سے ڈیزائن "whys" کو پُر کریں۔ نوٹ کریں کہ کتنے مراحل طے کرنے کی ضرورت ہے اور آپ نے کتنے "کیوں" شامل کیے ہیں۔
چیک لسٹ
- دستاویزات میں، میں "کیا/کیسے" اور "کیوں" پرتوں میں فرق کرتا ہوں۔
- میں AI کو "کیوں" بناتا نہیں، میں اسے خود شامل کرتا ہوں۔
- میں ٹارگٹ سامعین اور اصل سورس فائلوں کو پرامپٹ دیتا ہوں۔
- [ ] میں AI کی طرف سے نشان زد کردہ پوائنٹس کو ذاتی طور پر عمل میں لا کر ان کی تصدیق کرتا ہوں۔
- میں غیر ضروری تبصروں کو ختم کرتا ہوں جو کوڈ کو دہراتے ہیں۔
- میں دستاویزات کی تازہ کاری کو کوڈ کی تبدیلی کا حصہ بنا رہا ہوں۔