Gnóthachain:
- Cumas dréachtaí README, docstring agus changelog a tháirgeadh bunaithe ar spriocghrúpa agus foinse le AI
- Cumas na sraitheanna 'cad/conas' agus 'cén fáth' a scaradh sa doiciméadú agus an 'cén fáth' a chur leis mar dhuine.
- Na céimeanna suiteála a fhíorú trí iad a rith go pearsanta agus an doiciméad a dhéanamh mar chuid den athrú cód
Is é an doiciméadú an chuid de bhogearraí a ndéantar faillí orthu go minic ach is faide a mhaireann. Tá an cód inléite fiú tar éis míonna; Tá an té a scríobh sé imithe, déantar dearmad ar an gcomhthéacs, agus níl fágtha ach an méid a scríobhadh. Cinneann README maith (doiciméad tosaigh a mhíníonn cad is tionscadal ann agus conas é a shuiteáil agus a rith), tráchtanna cód míniúcháin agus doiciméadú API cothrom le dáta (tagairt a mhíníonn conas comhéadan a úsáid) luas foirne a chinneadh go díreach. Baineann AI go leor den “tuirse scríbhneoireachta” as doiciméadú - ach tagann gaiste leis: is féidir le AI tátal a bhaint as an gcód cad a dhéanann sé, ach is minic nach mbíonn a fhios aige cén fáth go ndéantar é ar an mbealach sin.
San aonad seo, foghlaimeoidh tú conas README, tráchtaireacht chód, docstring (bloc tuairimí scríofa in aghaidh na feidhme/ranga), doiciméad API agus loga athraithe a tháirgeadh le AI; agus conas an chuid is luachmhaire den doiciméadú a chaomhnú go daonna: an “cén fáth.”
Idirdhealú idir "Cad" agus "Cén Fáth"
Tá dhá shraith doiciméadaithe ann. Is é an chéad rud / conas: "sórtáil an fheidhm seo liosta", "rith an t-ordú seo chun a shuiteáil". Is féidir iad seo a bhaint as an gcód agus as an struchtúr; Tá AI ar fheabhas anseo. Ar an dara dul síos, cén fáth: "cén fáth a ndearnamar an tseirbhís seo asincrónach seachas sioncronach", "cén fáth a bhfuil an teorainnluach seo 30 soicind", "cén fáth ar roghnaigh muid an leabharlann seo thar an gceann eile". Níl siad seo scríofa sa chód; Tá sé mar thoradh ar chinntí dearaidh, srianta, agus pian san am atá caite.
níl a fhios ag AI "cén fáth"; Ar an mbealach is fearr, is buille faoi thuairim réasúnta atá ann - rud atá contúirteach, toisc go bhfuil cúis mícheart níos measa ná aon chúis ar chor ar bith. Mar sin tá roinnt an tsaothair soiléir: dréachtaíonn AI an "cad / conas," cuireann tú an "cén fáth." Is é an trácht is luachmhaire ná an ceann a deir cad nach féidir leis an gcód a rá.
Leid: Ná déan an méid a deir an cód féin go soiléir arís le trácht (cosúil le i = i + 1 // méadú i ar cheann). Uaireanta cuireann AI tráchtanna iomarcacha den sórt sin ar fáil; Scrios iad agus caith do chuid fuinnimh ar thuairimí “cén fáth”.
Céim ar Chéim: Giniúint Doiciméadúcháin le AI
- Sonraigh an spriocghrúpa. “Forbróir atá díreach ag tosú amach,” “an fhoireann sheachtrach a úsáidfidh an API seo,” “an todhchaí dom” — leagann an lucht éisteachta an ton teanga agus doimhneachta.
- Tabhair an fhoinse. Cuir an cód ábhartha, README reatha, úsáid shamplach leis an leid. Is cuireadh chun monaraithe é doiciméad neamhfhoinsithe.
- Struchtúr forchuir. Codanna caighdeánacha do README (Cuspóir, Suiteáil, Úsáid, Cumraíocht, Ranníocaíocht), formáid tionscadail le haghaidh docstring.
- Marcáil na spásanna "cén fáth". Iarr ar an AI cinntí nach bhfuil an réasúnaíocht ar eolas aige ina leith a mharcáil mar “tá nóta ‘cén fáth’ ag teastáil anseo”; Ansin líonann tú na bearnaí sin.
- Fíoraigh. Rith na céimeanna suiteála i ndáiríre; bain triail as an gcód samplach. Tá README nach n-oibríonn níos measa ná README ar bith.
Trí Chás Mini
Cás 1 – bordáil luathaithe README. Bhí uirlis foinse oscailte README in easnamh; Bhí deacrachtaí ag rannpháirtithe nua leis an suiteáil ar feadh 2 uair ar an meán. Thug an fhoireann na scripteanna suiteála agus package.json do AI agus dhréachtaigh siad README struchtúrtha, ansin rith na céimeanna iad féin ar mheaisín glan agus chuir siad an dá spleáchas ar iarraidh. Laghdaigh an t-am suiteála do rannpháirtithe ina dhiaidh sin go dtí 25 nóiméad ar an meán.
Cás 2 - An gaiste "cén fáth" comhdhéanta. D’iarr forbróir ar an AI nóta tráchta in aice le luach Teorainn ama ( Teorainn ama = 30 ). Scríobh an AI fírinniú réasúnta ach mícheart "chun latency líonra ard a fhulaingt"; ba é an fíorchúis ná teorainn chonarthach 30 soicind seirbhíse iartheachtacha. Mar thoradh ar an míthuiscint d'ardaigh forbróir ina dhiaidh sin an luach gan ghá, rud a d'eascair eachtra. Ceacht: ní mór d'úinéir an chóid an bonn cirt a fhíorú.
Cás 3 — Tá an caighdeán Docstring éirithe uathoibrithe. Ní raibh aon docstrings ag modúl cúnta le 40 feidhm. Tugadh an fhormáid tionscadail (stíl Google) don AI agus tháirg sé tuairiscí paraiméadar, tuairisceáin agus eisceachta do gach feidhm; D'athbhreithnigh an forbróir iad seo agus shocraigh sé roinnt dearbhú mícheart. Chuaigh doiciméadú 40 feidhm síos ó thart ar leath lae go uair an chloig.
Ceithre Theimpléad Inchóipeála
Dréacht struchtúrtha README:
Spriocghrúpa: {{ e.g. ranníocóir nua}}.Scríobh dréacht README bunaithe ar na comhaid thíos. Ailt: Aidhm, Gnéithe, Riachtanais, Suiteáil, Oibriú, Cumraíocht, Tástáil, Ranníocaíocht. Sliocht orduithe suiteála/reáchtála ó chomhaid iarbhír; FEISTIÚ. Marcáil na háiteanna nach bhfuil tú cinnte le "[VERIFY]". Foinse: {{package.json / scripts / sample code}}
Tagairt docstring/API:
Scríobh teaghrán doiciméadaithe do na feidhmeanna seo i bhformáid {{stíl tionscadail: Google/NumPy/JSDoc}}: achoimre ghearr, paraiméadair (cineál + brí), tuairisceán, eisceachtaí caite, 1 shampla gearr. Ná déan an méid a deir an cód go soiléir arís. Marcáil cinntí dearaidh a éilíonn "cén fáth" mar "[CÉN FÁTH GÁ]", ná scríobh fírinniú déanta.{{code}}
Bain spásanna le haghaidh nóta tráchta "cén fáth":
Sa chód seo, seans go bhfiafródh an chéad fhorbróir eile "cén fáth a bhfuil sé seo amhlaidh?" (uimhreacha draíochta, cinntí neamhghnácha, réitigh oibre). Tabhair trácht SCEIMHLITHEOIREACHTA do gach ceann acu, ach fág an réasúnaíocht BÁN; Líonfaidh mé an bonn cirt.{{code}}
Ráiteas Changelog/PR:
Scríobh {{changelog entry /PR description}} ón difríocht thíos. Formáid: Cad a d'athraigh (i dteanga úsáideora), Cén fáth (saincheist: {{...}}), Athrú a bhriseadh (más ann dó), Ar tástáladh é. Cuir béarlagair teicniúil in oiriúint don spriocghrúpa.{{dif}}
Leid lag / Pras láidir
Lag: "Scríobh README don tionscadal seo."
Strong: "Spriocghrúpa: forbróir ag clónáil an repo seo den chéad uair. Bunaithe ar an bpacáiste ceangailte.json, docker-compose.yml agus scripteanna/fillteán, scríobh dréacht README leis na hailt Aidhm, Riachtanais, Suiteáil, Oibríocht, Tástáil, Ranníocaíocht. Sliocht na horduithe ó na comhaid seo, ná déan suas iad; marcáil áit ar bith nach bhfuil tú cinnte le [VERIFY]."
Tugann an leagan láidir an lucht féachana, an fhoinse, an struchtúr, agus an riail “déan é, marcáil é”; ionas go mbeidh an doiciméad bunaithe ar fhíorchomhaid agus go bhfuil na háiteanna atá le fíorú le feiceáil go soiléir.
Cineál doiciméid
Déanann AI go maith
Cuireann / fíoraíonn an duine
Suiteáil README
imlíne chéim
Rith na céimeanna agus a dhearbhú
Teaghrán doiciméad/API
Struchtúr, paraiméadar, cineál
Cineál ceart agus "cén fáth"
Trácht cód
"Cad atá ar siúl aige" achoimre
"Cén fáth é seo" údar
Changelog/PR
chéad dréacht
Tionchar agus cruinneas
Cinneadh ailtireachta (ADR)
creatlach
Cinntí fíor agus comhréitigh
Doiciméadúchán Éilíonn Cothabháil
Is í an ghné is contúirtí de dhoiciméad ná nuair is cosúil go bhfuil sé fíor cé go bhfuil sé bréagach. Nuair a athraíonn an cód agus nach ndéantar an doiciméad a nuashonrú, cuireann sé an léitheoir amú go gníomhach. Éascaíonn AI nuashonrú: eisigh difríocht agus fiafraigh “cé na codanna den doiciméad a mbíonn tionchar ag an athrú seo orthu?” is féidir leat a iarraidh. Ach is é an próiseas a chinntíonn cothrom le dáta — déan an nuashonrú ar an doiciméadú mar chuid den athrú cód (critéar glactha PR). Luathaíonn AI; Tógann an fhoireann smacht.
Aire: Ná foilsigh gan na céimeanna suiteála i README a fhíorú. Is féidir le doiciméad "obair is dócha" céad lá forbróra nua a mhilleadh agus iontaobhas a chreimeadh. Rith na céimeanna tú féin i dtimpeallacht ghlan.
Botúin choitianta
- An “cén fáth” a fháil a d’oirfeadh don AI. Is measa fírinniú bréagach ná aon fhírinniú; Ba cheart d'úinéir an chóid an chúis dearaidh a scríobh.
- Gan na céimeanna suiteála a fhíorú. Scriosann README nach n-oibríonn muinín.
- Trácht gan ghá ag athrá an chóid. Táirgeann sé torann, doiléir léirmhínithe fíor "cén fáth".
- Gan an spriocghrúpa a shonrú. Ní dhéanfaidh doiciméad nach bhfuil soiléir cé chuige a bhfuil sé scríofa aon úsáid ag an novice nó an saineolaí.
- An nuashonrú a scaradh ón bpróiseas. Mura ndéantar an doiciméad a nuashonrú leis an gcód éiríonn sé míthreorach go tapa.
Go hachomair
Baineann AI go leor den ualach meicniúil as an doiciméadú: dréachtaí tapa README, docstring, tagairt API, changelog agus tuairiscí PR. Ach ní féidir a fhios ag an "cén fáth", a bhfuil an ciseal is luachmhaire, agus tá sé contúirteach a dhéanamh suas. Tá roinnt an tsaothair soiléir: táirgeann AI an "cad / conas," cuireann tú an "cén fáth." Sonraigh an lucht féachana, cuir acmhainní ar fáil, cuir struchtúr i bhfeidhm, marcáil áiteanna le feistiú, agus fíoraigh gach céim suiteála trína rith tú féin. Déan doiciméadú mar chuid lárnach den athrú cód.
Tasc feidhmchláir
Roghnaigh modúl nó tionscadal beag a bhfuil a dhoiciméadú in easnamh nó as dáta. Gin imlíne ar dtús ó AI leis an teimpléad “dréacht struchtúrtha README” (nó docstring); Bí cinnte a thabhairt ar an fhoinse agus lucht éisteachta sprioc. Ansin, téigh trí gach pointe ina bhfuil an AI marcáilte [Fíoraigh] nó [CÉN FÁTH TEASTÁIL]: reáchtáil na céimeanna socraithe i ndáiríre agus líon isteach an dearadh “cén fáth” le do chuid eolais féin. Tabhair faoi deara cé mhéad céim is gá a shocrú agus cé mhéad “cén fáth” a chuir tú leis.
seicliosta
- [ ] Sna doiciméid, déanaim idirdhealú idir na sraitheanna "cad/conas" agus "cén fáth".
- [ ] Ní féidir liom a dhéanamh ar an AI a dhéanamh suas an "cén fáth", cuirim mé féin é.
- [ ] Tugaim an leid don spriocghrúpa agus na comhaid foinse iarbhír.
- [ ] Deimhním na pointí [FÍORÚ] atá marcáilte ag an AI trína fhorghníomhú go pearsanta.
- [ ] Cuirim deireadh le tuairimí nach bhfuil gá leo a dhéanann an cód arís.
- [ ] Tá an nuashonrú doiciméadúcháin á dhéanamh agam mar chuid den athrú cód.