Qligħ:
- Kapaċità li tipproduċi abbozzi README, docstring u changelog ibbażati fuq udjenza fil-mira u sors bl-AI
- Kapaċità li tissepara s-saffi 'x'/kif' u 'għaliex' fid-dokumentazzjoni u żżid il-'għaliex' bħala bniedem
- Li tivverifika l-passi tal-installazzjoni billi tmexxihom personalment u tagħmel id-dokument parti mill-bidla tal-kodiċi
Il-parti tas-software l-aktar frekwentement traskurata iżda li ddum itwal hija d-dokumentazzjoni. Il-kodiċi jinqara anke wara xhur; Il-persuna li kitebha marret, il-kuntest jintesa, u jibqa’ biss dak li nkiteb. README tajjeb (dokument introduttorju li jispjega x'inhu proġett u kif tinstallah u tħaddem), kummenti ta' kodiċi ta' spjegazzjoni u dokumentazzjoni API aġġornata (referenza li tispjega kif tuża interface) jiddeterminaw direttament il-veloċità ta 'tim. L-AI tieħu ħafna mill-"għeja tal-kitba" mid-dokumentazzjoni - iżda tiġi flimkien ma 'nassa: l-AI tista' tiddeduċi mill-kodiċi x'tagħmel, iżda ħafna drabi ma tistax tkun taf għaliex dan isir b'dan il-mod.
F'din l-unità, int se titgħallem kif tipproduċi README, kumment tal-kodiċi, docstring (blokk ta 'kummenti miktub għal kull funzjoni/klassi), dokument API u changelog bl-AI; u kif umanament tippreserva l-aktar parti siewja tad-dokumentazzjoni: il-"għaliex."
Distinzjoni bejn "Xi" u "Għaliex"
Hemm żewġ saffi ta 'dokumentazzjoni. L-ewwel huwa dak/kif: "din il-funzjoni issortja lista", "run dan il-kmand biex tinstalla". Dawn jistgħu jiġu estratti mill-kodiċi u l-istruttura; L-AI teċċella hawn. It-tieni, għaliex: "għaliex għamilna dan is-servizz mhux sinkroniku aktar milli sinkroniku", "għaliex dan il-valur tal-limitu huwa 30 sekonda", "għaliex għażilna din il-librerija fuq l-oħra". Dawn mhumiex miktuba fil-kodiċi; Huwa l-prodott ta 'deċiżjonijiet ta' disinn, restrizzjonijiet, u uġigħ fil-passat.
AI ma tafx "għaliex"; Fl-aħjar, din tagħmel suppożizzjoni raġonevoli—li hija perikoluża, għax raġuni ħażina hija agħar minn ebda raġuni. Allura d-diviżjoni tax-xogħol hija ċara: AI tabbozza l-"x'/kif", inti żżid il-"għaliex." L-aktar kumment siewi huwa dak li jgħid dak li l-kodiċi ma jistax jgħid.
Tip: Tirrepetix b'kumment dak li jgħid b'mod ċar il-kodiċi innifsu (bħal i = i + 1 // żid i b'wieħed). L-AI kultant tipproduċi kummenti żejda bħal dawn; Eliminahom u ddedika l-enerġija tiegħek għall-kummenti "għaliex".
Pass pass: Ġenerazzjoni ta' Dokumentazzjoni bl-AI
- Speċifika l-udjenza fil-mira. "Żviluppatur għadu qed jibda", "it-tim estern li se juża din l-API", "il-futur jien" - l-udjenza tistabbilixxi t-ton għal-lingwa u l-profondità.
- Agħti s-sors. Żid il-kodiċi rilevanti, README eżistenti, użu eżempju fil-pront. Dokument mingħajr sors huwa stedina għall-fabbrikazzjoni.
- Struttura ta' impożizzjoni. Sezzjonijiet standard għal README (Għan, Installazzjoni, Użu, Konfigurazzjoni, Kontribuzzjoni), format tal-proġett għal docstring.
- Immarka l-ispazji "għaliex". Staqsi lill-AI biex timmarka deċiżjonijiet li għalihom ma tafx ir-raġuni għaliex "hawnhekk hija meħtieġa nota 'għaliex'"; Imbagħad timla dawk il-vojt.
- Ivverifika. Attwalment mexxi l-passi tal-installazzjoni; ipprova l-kodiċi tal-kampjun. README li ma jaħdimx huwa agħar minn ebda README.
Tliet Każijiet Mini
Każ 1 — README onboarding aċċellerat. README ta' għodda ta' sors miftuħ kien nieqes; Kontributuri ġodda tħabtu ma 'l-installazzjoni għal medja ta' sagħtejn. It-tim ta l-iskripts tal-installazzjoni u package.json lill-AI u abbozza README strutturat, imbagħad mexxa l-passi huma stess fuq magna nadifa u żied iż-żewġ dipendenzi neqsin. Il-ħin tal-installazzjoni għall-kontributuri sussegwenti naqas għal medja ta’ 25 minuta.
Każ 2 — In-nassa “għaliex” magħmula. Żviluppatur talab lill-AI għal kumment ħdejn valur ta' timeout (timeout=30). L-AI kitbet ġustifikazzjoni raġonevoli iżda mhux korretta "biex tittollera latenza għolja tan-netwerk"; ir-raġuni vera kienet il-limitu kuntrattwali ta' 30 sekonda ta' servizz downstream. L-interpretazzjoni ħażina wasslet lil żviluppatur sussegwenti biex iżid il-valur bla bżonn, li wassal għal inċident. Lezzjoni: is-sid tal-kodiċi għandu jivverifika l-ġustifikazzjoni.
Każ 3 — L-istandard Docstring sar awtomatizzat. Modulu awżiljarju b'40 funzjoni ma kellu l-ebda docstrings. L-AI ingħatat il-format tal-proġett (stil Google) u pproduċiet deskrizzjonijiet ta 'parametri, ritorn u eċċezzjoni għal kull funzjoni; L-iżviluppatur irreveda dawn u ffissa ftit dikjarazzjonijiet tat-tip mhux korretti. Id-dokumentazzjoni ta’ 40 funzjoni niżlet minn madwar nofs ġurnata għal siegħa.
Erba' Mudelli Kopjabbli
Abbozz strutturat README:
Udjenza fil-mira: {{eż. kontributur ġdid}}. Ikteb abbozz README ibbażat fuq il-fajls hawn taħt. Taqsimiet: Għan, Karatteristiċi, Rekwiżiti, Installazzjoni, Operazzjoni, Konfigurazzjoni, Ittestjar, Kontribuzzjoni. Oħroġ il-kmandi ta' installazzjoni/tmexxija minn fajls attwali; TWAĦĦIL. Immarka l-postijiet li m'intix ċert bi "[VERIFIKA]". Sors: {{package.json / scripts / sample code}}
Referenza tad-Docstring/API:
Ikteb docstring għal dawn il-funzjonijiet f'format {{stil tal-proġett: Google/NumPy/JSDoc}}: sommarju qasir, parametri (tip + tifsira), ritorn, eċċezzjonijiet mitfugħa, eżempju qasir 1. Irrepetix dak li jgħid il-kodiċi KAR. Immarka d-deċiżjonijiet tad-disinn li jeħtieġu "għaliex" bħala "[GĦALIEX MEĦTIEĠ]", tiktebx ġustifikazzjoni ffabbrikata.{{code}}
Neħħi l-ispazji għall-kumment "għaliex":
F'dan il-kodiċi, l-iżviluppatur li jmiss jista 'jistaqsi "għaliex dan huwa hekk?" (numri maġiċi, deċiżjonijiet mhux tas-soltu, soluzzjonijiet). Agħti kumment SKELETTU għal kull wieħed, iżda ħalli r-raġuni vojta; Se nimla l-ġustifikazzjoni.{{code}}
Dikjarazzjoni tar-reġistru tal-bidliet/PR:
Ikteb {{changelog entry / PR description}} mid-diff hawn taħt. Format: X'inbidel (fil-lingwa tal-utent), Għaliex (ħarġa: {{...}}), Tkissir tal-bidla (jekk hemm), Ġie ttestjat. Aġġusta l-lingwaġġ tekniku għall-udjenza fil-mira.{{diff}}
Pront dgħajjef / Pront qawwi
Dgħajjef: "Ikteb README għal dan il-proġett."
Qawwija: "Udjenza fil-mira: żviluppatur li jikklona dan ir-repo għall-ewwel darba. Ibbażat fuq package.json, docker-compose.yml u skripts/ folder mehmuż, ikteb abbozz README bi Għan, Rekwiżiti, Installazzjoni, Operazzjoni, Ittestjar, Kontribuzzjoni sezzjonijiet. Oħroġ il-kmandi minn dawn il-fajls, ma tagħmilhomx;
Il-verżjoni b'saħħitha tagħti lill-udjenza, is-sors, l-istruttura, u r-regola "għamilha, immarkaha"; sabiex id-dokument ikun ibbażat fuq fajls reali u l-postijiet li jridu jiġu vverifikati jkunu viżibbli b'mod ċar.
Tip ta' dokument
AI tagħmel tajjeb
Bniedem iżid/jivverifika
Installazzjoni README
kontorn tal-pass
Mexxi l-passi u kkonferma
Docstring/API
Struttura, parametru, tip
Tip korrett u "għaliex"
Kumment tal-kodiċi
Sommarju "Dak li qed jagħmel".
"Għaliex din" ġustifikazzjoni
Changelog/PR
l-ewwel abbozz
Impatt u preċiżjoni
Deċiżjoni tal-arkitettura (ADR)
iskeletru
Deċiżjonijiet reali u kompromessi
Dokumentazzjoni Teħtieġ Manutenzjoni
L-aktar aspett perikoluż ta' dokument huwa meta jidher veru minkejja li huwa falz. Meta l-kodiċi jinbidel u d-dokument ma jiġix aġġornat, iqarraq b'mod attiv lill-qarrej. L-AI tagħmel l-aġġornament faċli: toħroġ diff u staqsi "liema partijiet tad-dokument taffettwa din il-bidla?" tista' tistaqsi. Iżda huwa l-proċess li jiżgura l-aġġornament — tagħmel l-aġġornament tad-dokumentazzjoni parti mill-bidla tal-kodiċi (kriterju ta 'aċċettazzjoni ta' PR). AI taċċellera; It-tim jibni d-dixxiplina.
Attenzjoni: Tippubblikax mingħajr ma tivverifika l-passi tal-installazzjoni f'README. Dokument "probabbilment tax-xogħol" jista 'jrovina l-ewwel jum ta' żviluppatur ġdid u jnaqqas il-fiduċja. Mexxi l-passi lilek innifsek f'ambjent nadif.
Żbalji komuni
- Jkollna l-"għaliex" biex taqbel mal-AI. Ġustifikazzjoni falza hija agħar minn ebda ġustifikazzjoni; Is-sid tal-kodiċi għandu jikteb ir-raġuni tad-disinn.
- Mhux jivverifika l-passi tal-installazzjoni. README li ma taħdimx jeqred il-fiduċja.
- Kumment bla bżonn li jirrepeti l-kodiċi. Jipproduċi ħsejjes, li joskuraw interpretazzjonijiet reali "għaliex".
- Mhux tispeċifika l-udjenza fil-mira. Dokument li ma jkunx ċar lil min ikun miktub ma huwa ta’ ebda użu la għan-novizz u lanqas għall-espert.
- Tissepara l-aġġornament mill-proċess. Jekk id-dokument ma jiġix aġġornat bil-kodiċi malajr isir qarrieqi.
Fil-qosor
L-AI tieħu ħafna mill-piż mekkaniku mid-dokumentazzjoni: abbozzi ta' malajr README, docstring, referenza API, changelog u deskrizzjonijiet PR. Iżda ma tistax tkun taf il-"għaliex", li huwa l-aktar saff ta 'valur, u huwa perikoluż li tagħmel dan. Id-diviżjoni tax-xogħol hija ċara: l-AI tipproduċi "x'/kif", inti żżid il-"għaliex." Speċifika l-udjenza, ipprovdi riżorsi, imponi struttura, immarka l-postijiet biex toqgħod, u ivverifika kull pass ta 'installazzjoni billi tmexxiha lilek innifsek. Agħmel id-dokumentazzjoni parti integrali mill-bidla tal-kodiċi.
Kompitu ta' applikazzjoni
Agħżel modulu jew proġett żgħir li d-dokumentazzjoni tiegħu hija nieqsa jew skaduta. L-ewwel iġġenera deskrizzjoni mill-AI bil-mudell ta '"abbozz strutturat README" (jew docstring); Kun żgur li tagħti s-sors u l-udjenza fil-mira. Imbagħad għaddi minn kull punt fejn l-AI tkun immarkat [VERIFIKA] jew [GĦALIEX MEĦTIEĠ]: fil-fatt mexxi l-passi tas-setup u imla d-disinn "għaliex" bl-għarfien tiegħek stess. Innota kemm jeħtieġ li jiġu ffissati passi u kemm "għaliex" żidt.
lista ta' kontroll
- [ ] Fid-dokumentazzjoni, niddistingwi s-saffi "x'/kif" u "għaliex".
- [ ] L-AI ma nagħmelx il-"għaliex", inżidha jien stess.
- [ ] Nagħti lill-pront l-udjenza fil-mira u l-fajls tas-sors attwali.
- [ ] Nivverifika l-punti [VERIFIKA] immarkati mill-AI billi nwettaqhom personalment.
- [ ] Nelimina kummenti bla bżonn li jirrepetu l-kodiċi.
- [ ] Qed nagħmel l-aġġornament tad-dokumentazzjoni parti mill-bidla tal-kodiċi.