డాక్యుమెంటేషన్, README మరియు కోడ్ వ్యాఖ్యలు

లాభాలు:

• AIతో లక్ష్య ప్రేక్షకులు మరియు మూలం ఆధారంగా README, డాక్‌స్ట్రింగ్ మరియు చేంజ్‌లాగ్ డ్రాఫ్ట్‌లను రూపొందించగల సామర్థ్యం
• డాక్యుమెంటేషన్‌లో 'ఏమి/ఎలా' మరియు 'ఎందుకు' లేయర్‌లను వేరు చేసి, మానవునిగా 'ఎందుకు' జోడించగల సామర్థ్యం
• ఇన్‌స్టాలేషన్ దశలను వ్యక్తిగతంగా అమలు చేయడం ద్వారా వాటిని ధృవీకరించడం మరియు పత్రాన్ని కోడ్ మార్పులో భాగంగా చేయడం

సాఫ్ట్‌వేర్‌లో చాలా తరచుగా నిర్లక్ష్యం చేయబడిన కానీ ఎక్కువ కాలం ఉండే భాగం డాక్యుమెంటేషన్. నెలల తర్వాత కూడా కోడ్ చదవబడుతుంది; రాసిన వాడు పోయాడు, సందర్భం మరిచిపోయి, రాసినది మాత్రమే మిగిలిపోయింది. ఒక మంచి README (ప్రాజెక్ట్ అంటే ఏమిటి మరియు దానిని ఎలా ఇన్‌స్టాల్ చేసి రన్ చేయాలో వివరించే పరిచయ పత్రం), వివరణాత్మక కోడ్ వ్యాఖ్యలు మరియు తాజా API డాక్యుమెంటేషన్ (ఇంటర్‌ఫేస్‌ను ఎలా ఉపయోగించాలో వివరించే సూచన) నేరుగా బృందం వేగాన్ని నిర్ణయిస్తుంది. AI డాక్యుమెంటేషన్ నుండి చాలా "వ్రాత అలసట"ని తీసుకుంటుంది - కానీ ఇది ఒక ఉచ్చుతో వస్తుంది: AI కోడ్ నుండి ఏమి చేస్తుందో ఊహించగలదు, కానీ అది ఎందుకు అలా జరిగిందో తరచుగా తెలియదు.

ఈ యూనిట్‌లో, AIతో README, కోడ్ కామెంట్, డాక్‌స్ట్రింగ్ (ఫంక్షన్/క్లాస్‌కి వ్రాసిన వ్యాఖ్య బ్లాక్), API డాక్యుమెంట్ మరియు చేంజ్‌లాగ్‌ని ఎలా ఉత్పత్తి చేయాలో మీరు నేర్చుకుంటారు; మరియు డాక్యుమెంటేషన్‌లోని అత్యంత విలువైన భాగాన్ని మానవీయంగా ఎలా భద్రపరచాలి: "ఎందుకు."

"ఏమి" మరియు "ఎందుకు" మధ్య వ్యత్యాసం

డాక్యుమెంటేషన్‌లో రెండు పొరలు ఉన్నాయి. మొదటిది ఏమిటి/ఎలా: "ఈ ఫంక్షన్ జాబితాను క్రమబద్ధీకరిస్తుంది", "ఇన్‌స్టాల్ చేయడానికి ఈ ఆదేశాన్ని అమలు చేయండి". వీటిని కోడ్ మరియు నిర్మాణం నుండి సంగ్రహించవచ్చు; AI ఇక్కడ రాణిస్తోంది. రెండవది, ఎందుకు: "మేము ఈ సేవను సింక్రోనస్ కాకుండా అసమకాలికంగా ఎందుకు చేసాము", "ఈ పరిమితి విలువ 30 సెకన్లు ఎందుకు", "మేము ఈ లైబ్రరీని మరొకదాని కంటే ఎందుకు ఎంచుకున్నాము". ఇవి కోడ్‌లో వ్రాయబడలేదు; ఇది డిజైన్ నిర్ణయాలు, పరిమితులు మరియు గత నొప్పి యొక్క ఉత్పత్తి.

AIకి "ఎందుకు" తెలియదు; ఉత్తమంగా, ఇది సహేతుకమైన అంచనాను కలిగి ఉంటుంది-ఇది ప్రమాదకరమైనది, ఎందుకంటే తప్పు కారణం ఎటువంటి కారణం కంటే ఘోరంగా ఉంటుంది. కాబట్టి శ్రమ విభజన స్పష్టంగా ఉంది: AI డ్రాఫ్ట్ “ఏమి/ఎలా,” మీరు “ఎందుకు” జోడించండి. కోడ్ చెప్పలేనిది చెప్పేది అత్యంత విలువైన వ్యాఖ్య.

చిట్కా: కోడ్ స్పష్టంగా ఏమి చెబుతుందో వ్యాఖ్యతో పునరావృతం చేయవద్దు (i = i + 1 // iని ఒక్కొక్కటిగా పెంచండి). AI కొన్నిసార్లు ఇటువంటి పునరావృత వ్యాఖ్యలను ఉత్పత్తి చేస్తుంది; వాటిని తొలగించి, "ఎందుకు" వ్యాఖ్యలకు మీ శక్తిని వెచ్చించండి.

దశల వారీగా: AIతో డాక్యుమెంటేషన్ జనరేషన్

1. లక్ష్య ప్రేక్షకులను పేర్కొనండి. “ఇప్పుడే ప్రారంభించిన డెవలపర్,” “ఈ APIని ఉపయోగించే బాహ్య బృందం,” “భవిష్యత్తు నేను” — ప్రేక్షకులు భాష మరియు లోతు కోసం టోన్‌ని సెట్ చేస్తారు.
2. మూలం ఇవ్వండి. సంబంధిత కోడ్, ఇప్పటికే ఉన్న README, ఉదాహరణ వినియోగాన్ని ప్రాంప్ట్‌కు జోడించండి. మూలం లేని పత్రం అనేది కల్పనకు ఆహ్వానం.
3. విధింపు నిర్మాణం. README (పర్పస్, ఇన్‌స్టాలేషన్, యూసేజ్, కాన్ఫిగరేషన్, కంట్రిబ్యూషన్) కోసం ప్రామాణిక విభాగాలు, డాక్‌స్ట్రింగ్ కోసం ప్రాజెక్ట్ ఫార్మాట్.
4. "ఎందుకు" ఖాళీలను గుర్తించండి. "ఎందుకు' గమనిక ఇక్కడ అవసరం" అని హేతుబద్ధత తెలియని నిర్ణయాలను గుర్తించమని AIని అడగండి; అప్పుడు మీరు ఆ ఖాళీలను పూరించండి.
5. ధృవీకరించండి. వాస్తవానికి సంస్థాపనా దశలను అమలు చేయండి; నమూనా కోడ్‌ని ప్రయత్నించండి. పని చేయని README ఏ README కంటే అధ్వాన్నంగా ఉంది.

మూడు మినీ కేసులు

కేస్ 1 — README వేగవంతమైన ఆన్‌బోర్డింగ్. ఓపెన్ సోర్స్ సాధనం యొక్క README లేదు; కొత్త కంట్రిబ్యూటర్‌లు సగటున 2 గంటల పాటు ఇన్‌స్టాలేషన్‌తో ఇబ్బంది పడ్డారు. బృందం AIకి ఇన్‌స్టాలేషన్ స్క్రిప్ట్‌లు మరియు ప్యాకేజీ.jsonని అందించింది మరియు ఒక నిర్మాణాత్మక READMEని రూపొందించింది, ఆపై స్టెప్స్‌ను స్వయంగా ఒక క్లీన్ మెషీన్‌లో అమలు చేసింది మరియు రెండు మిస్సింగ్ డిపెండెన్సీలను జోడించింది. తదుపరి సహకారుల కోసం ఇన్‌స్టాలేషన్ సమయం సగటున 25 నిమిషాలకు తగ్గింది.

కేసు 2 - తయారు చేయబడిన "ఎందుకు" ఉచ్చు. డెవలపర్ గడువు ముగిసిన విలువ (సమయం ముగిసింది=30) పక్కన వ్యాఖ్య కోసం AIని అడిగారు. "అధిక నెట్‌వర్క్ జాప్యాన్ని తట్టుకోవడానికి" AI సహేతుకమైన కానీ తప్పు సమర్థనను వ్రాసింది; అసలు కారణం దిగువ సేవ యొక్క ఒప్పంద 30-సెకన్ల పరిమితి. తప్పుడు వ్యాఖ్యానం తదుపరి డెవలపర్ విలువను అనవసరంగా పెంచడానికి దారితీసింది, ఇది ఒక సంఘటనకు దారితీసింది. పాఠం: కోడ్ యజమాని తప్పనిసరిగా సమర్థనను ధృవీకరించాలి.

కేస్ 3 — డాక్‌స్ట్రింగ్ ప్రమాణం స్వయంచాలకంగా మారింది. 40 ఫంక్షన్‌లతో కూడిన సహాయక మాడ్యూల్‌లో డాక్‌స్ట్రింగ్‌లు లేవు. AIకి ప్రాజెక్ట్ ఫార్మాట్ (గూగుల్ స్టైల్) ఇవ్వబడింది మరియు ప్రతి ఫంక్షన్ కోసం పారామీటర్, రిటర్న్ మరియు మినహాయింపు వివరణలను రూపొందించింది; డెవలపర్ వీటిని సమీక్షించారు మరియు కొన్ని సరికాని టైప్ డిక్లరేషన్‌లను పరిష్కరించారు. 40 ఫంక్షన్‌లను డాక్యుమెంట్ చేయడం దాదాపు అర రోజు నుండి గంటకు తగ్గింది.

నాలుగు కాపీ చేయగల టెంప్లేట్లు

నిర్మాణాత్మక README డ్రాఫ్ట్:

లక్ష్య ప్రేక్షకులు: {{ఉదా. కొత్త కంట్రిబ్యూటర్}}.క్రింద ఉన్న ఫైల్‌ల ఆధారంగా డ్రాఫ్ట్ READMEని వ్రాయండి. విభాగాలు: ప్రయోజనం, ఫీచర్లు, అవసరాలు, ఇన్‌స్టాలేషన్, ఆపరేషన్, కాన్ఫిగరేషన్, టెస్టింగ్, కంట్రిబ్యూషన్. వాస్తవ ఫైల్‌ల నుండి ఇన్‌స్టాలేషన్/రన్నింగ్ కమాండ్‌లను సంగ్రహించండి; అమర్చడం. మీకు ఖచ్చితంగా తెలియని స్థలాలను "[VERIFY]"తో గుర్తించండి. మూలం: {{package.json / స్క్రిప్ట్‌లు / నమూనా కోడ్}}

డాక్‌స్ట్రింగ్/API సూచన:

{{ప్రాజెక్ట్ శైలి: Google/NumPy/JSDoc}} ఫార్మాట్‌లో ఈ ఫంక్షన్‌లకు డాక్‌స్ట్రింగ్‌ను వ్రాయండి: సంక్షిప్త సారాంశం, పారామీటర్‌లు (రకం + అర్థం), రిటర్న్, మినహాయింపులు విసిరారు, 1 చిన్న ఉదాహరణ. కోడ్ స్పష్టంగా చెప్పేదాన్ని పునరావృతం చేయవద్దు. "ఎందుకు" అవసరమయ్యే డిజైన్ నిర్ణయాలను "[ఎందుకు అవసరం]"గా గుర్తించండి, కల్పిత సమర్థనను వ్రాయవద్దు.{{code}}

"ఎందుకు" వ్యాఖ్య కోసం ఖాళీలను తీసివేయండి:

ఈ కోడ్‌లో, తదుపరి డెవలపర్ "ఎందుకు ఇలా జరిగింది?" (మేజిక్ సంఖ్యలు, అసాధారణ నిర్ణయాలు, పరిష్కారాలు). ప్రతిదానికి అస్థిపంజరం అని వ్యాఖ్యానించండి, కానీ హేతుబద్ధతను ఖాళీగా ఉంచండి; నేను సమర్థనను పూరిస్తాను.{{code}}

చేంజ్లాగ్/PR ప్రకటన:

దిగువ తేడా నుండి {{చేంజ్లాగ్ ఎంట్రీ / PR వివరణ}} వ్రాయండి. ఫార్మాట్: ఏమి మార్చబడింది (వినియోగదారు భాషలో), ఎందుకు (సమస్య: {{...}}), బ్రేకింగ్ మార్పు (ఏదైనా ఉంటే), ఇది పరీక్షించబడిందా. లక్ష్య ప్రేక్షకులకు సాంకేతిక పరిభాషను సర్దుబాటు చేయండి.{{diff}}

బలహీనమైన ప్రాంప్ట్ / బలమైన ప్రాంప్ట్

బలహీనం: "ఈ ప్రాజెక్ట్ కోసం READMEని వ్రాయండి."

బలమైనది: "లక్ష్య ప్రేక్షకులు: డెవలపర్ మొదటిసారిగా ఈ రెపోను క్లోన్ చేస్తారు. జోడించిన ప్యాకేజీ.json, docker-compose.yml మరియు స్క్రిప్ట్‌లు/ ఫోల్డర్ ఆధారంగా, ఉద్దేశ్యం, అవసరాలు, ఇన్‌స్టాలేషన్, ఆపరేషన్, టెస్టింగ్, కంట్రిబ్యూషన్ విభాగాలతో డ్రాఫ్ట్ READMEని వ్రాయండి. ఈ ఫైల్‌ల నుండి ఎక్కడా కమాండ్‌లను ఎక్స్‌ట్రాక్ట్ చేయవద్దు; [ధృవీకరించండి]."

బలమైన సంస్కరణ ప్రేక్షకులకు, మూలం, నిర్మాణం మరియు "మేక్ ఇట్, మార్క్ ఇట్" నియమాన్ని ఇస్తుంది; పత్రం నిజమైన ఫైల్‌లపై ఆధారపడి ఉంటుంది మరియు ధృవీకరించాల్సిన స్థలాలు స్పష్టంగా కనిపిస్తాయి.

పత్రం రకం

AI బాగా పనిచేస్తుంది

మానవుడు జోడిస్తుంది/ధృవపరుస్తుంది

README ఇన్‌స్టాలేషన్

దశ రూపురేఖలు

దశలను అమలు చేయండి మరియు నిర్ధారించండి

డాక్‌స్ట్రింగ్/API

నిర్మాణం, పరామితి, రకం

సరైన రకం మరియు "ఎందుకు"

కోడ్ వ్యాఖ్య

"అతను ఏమి చేస్తున్నాడు" సారాంశం

"ఎందుకు ఇది" సమర్థన

చేంజ్లాగ్/PR

మొదటి డ్రాఫ్ట్

ప్రభావం మరియు ఖచ్చితత్వం

నిర్మాణ నిర్ణయం (ADR)

అస్థిపంజరం

నిజమైన నిర్ణయాలు మరియు రాజీలు

డాక్యుమెంటేషన్ నిర్వహణ అవసరం

పత్రం యొక్క అత్యంత ప్రమాదకరమైన అంశం ఏమిటంటే, అది తప్పు అయినప్పటికీ అది నిజం. కోడ్ మారినప్పుడు మరియు పత్రం నవీకరించబడనప్పుడు, అది రీడర్‌ను చురుకుగా తప్పుదారి పట్టిస్తుంది. AI నవీకరణను సులభతరం చేస్తుంది: తేడాను జారీ చేసి, “ఈ మార్పు పత్రంలోని ఏ భాగాలను ప్రభావితం చేస్తుంది?” అని అడగండి. మీరు అడగవచ్చు. కానీ ఇది తాజాదనాన్ని నిర్ధారించే ప్రక్రియ - డాక్యుమెంటేషన్ నవీకరణను కోడ్ మార్పులో భాగంగా చేయండి (PR యొక్క అంగీకార ప్రమాణం). AI వేగవంతం; జట్టు క్రమశిక్షణను నిర్మిస్తుంది.

హెచ్చరిక: READMEలో ఇన్‌స్టాలేషన్ దశలను ధృవీకరించకుండా ప్రచురించవద్దు. "బహుశా పని" పత్రం కొత్త డెవలపర్ యొక్క మొదటి రోజును నాశనం చేస్తుంది మరియు నమ్మకాన్ని దెబ్బతీస్తుంది. శుభ్రమైన వాతావరణంలో దశలను మీరే నడపండి.

సాధారణ తప్పులు

• AIకి సరిపోయేలా "ఎందుకు" పొందడం. తప్పుడు సమర్థన ఏ సమర్థన కంటే ఘోరంగా ఉంటుంది; కోడ్ యజమాని డిజైన్ కారణాన్ని వ్రాయాలి.
• ఇన్‌స్టాలేషన్ దశలను ధృవీకరించడం లేదు. పని చేయని README నమ్మకాన్ని నాశనం చేస్తుంది.
• కోడ్‌ని పునరావృతం చేస్తూ అనవసరమైన వ్యాఖ్య. ఇది శబ్దాన్ని ఉత్పత్తి చేస్తుంది, నిజమైన "ఎందుకు" వివరణలను అస్పష్టం చేస్తుంది.
• లక్ష్య ప్రేక్షకులను పేర్కొనలేదు. ఎవరికి వ్రాయబడిందో అస్పష్టంగా ఉన్న పత్రం అనుభవం లేని వ్యక్తికి లేదా నిపుణుడికి ఎటువంటి ఉపయోగం లేదు.
• ప్రక్రియ నుండి నవీకరణను వేరు చేస్తోంది. పత్రం కోడ్‌తో అప్‌డేట్ చేయకపోతే అది త్వరగా తప్పుదారి పట్టించేదిగా మారుతుంది.

సారాంశంలో

AI డాక్యుమెంటేషన్ నుండి చాలా యాంత్రిక భారాన్ని తీసుకుంటుంది: శీఘ్ర చిత్తుప్రతులు README, docstring, API సూచన, చేంజ్లాగ్ మరియు PR వివరణలు. కానీ అది "ఎందుకు" అని తెలుసుకోలేకపోతుంది, ఇది అత్యంత విలువైన పొర, మరియు దానిని తయారు చేయడం ప్రమాదకరం. శ్రమ విభజన స్పష్టంగా ఉంది: AI "ఏమి/ఎలా" ఉత్పత్తి చేస్తుంది, మీరు "ఎందుకు" జోడించండి. ప్రేక్షకులను పేర్కొనండి, వనరులను అందించండి, నిర్మాణాన్ని విధించండి, సరిపోయేలా స్థలాలను గుర్తించండి మరియు ప్రతి ఇన్‌స్టాలేషన్ దశను మీరే అమలు చేయడం ద్వారా ధృవీకరించండి. కోడ్ మార్పులో డాక్యుమెంటేషన్‌ను అంతర్భాగంగా చేయండి.

అప్లికేషన్ టాస్క్

డాక్యుమెంటేషన్ తప్పిపోయిన లేదా పాతది అయిన మాడ్యూల్ లేదా చిన్న ప్రాజెక్ట్‌ను ఎంచుకోండి. ముందుగా "స్ట్రక్చర్డ్ README డ్రాఫ్ట్" (లేదా డాక్‌స్ట్రింగ్) టెంప్లేట్‌తో AI నుండి అవుట్‌లైన్‌ను రూపొందించండి; మూలాన్ని మరియు లక్ష్య ప్రేక్షకులను అందించాలని నిర్ధారించుకోండి. ఆపై AI మార్క్ చేసిన ప్రతి పాయింట్‌ను పరిశీలించండి [ధృవీకరించండి] లేదా [ఎందుకు అవసరం]: వాస్తవానికి సెటప్ దశలను అమలు చేయండి మరియు మీ స్వంత జ్ఞానంతో డిజైన్ “ఎందుకు” నింపండి. ఎన్ని దశలను పరిష్కరించాలి మరియు మీరు ఎన్ని "ఎందుకు" జోడించారో గమనించండి.

చెక్లిస్ట్

• [ ] డాక్యుమెంటేషన్‌లో, నేను "ఏమి/ఎలా" మరియు "ఎందుకు" లేయర్‌లను వేరు చేస్తున్నాను.
• [ ] నేను AIని "ఎందుకు" తయారు చేయను, నేనే దానిని జోడించాను.
• [ ] నేను ప్రాంప్ట్‌ని లక్ష్య ప్రేక్షకులకు మరియు వాస్తవ సోర్స్ ఫైల్‌లను అందిస్తాను.
• [ ] నేను వ్యక్తిగతంగా అమలు చేయడం ద్వారా AI ద్వారా గుర్తించబడిన [VERIFY] పాయింట్‌లను ధృవీకరిస్తాను.
• [ ] నేను కోడ్‌ను పునరావృతం చేసే అనవసరమైన వ్యాఖ్యలను తొలగిస్తాను.
• [ ] నేను డాక్యుమెంటేషన్ నవీకరణను కోడ్ మార్పులో భాగంగా చేస్తున్నాను.