Mga nadagdag:
- Kakayahang gumawa ng README, docstring at changelog draft batay sa target na audience at source na may AI
- Kakayahang paghiwalayin ang mga layer na 'ano/paano' at 'bakit' sa dokumentasyon at idagdag ang 'bakit' bilang isang tao
- Pag-verify ng mga hakbang sa pag-install sa pamamagitan ng personal na pagpapatakbo sa mga ito at paggawa ng dokumento bilang bahagi ng pagbabago ng code
Ang pinaka-madalas na napapabayaan ngunit pinakamatagal na bahagi ng software ay dokumentasyon. Ang code ay nababasa kahit na pagkatapos ng mga buwan; Ang taong sumulat nito ay wala na, ang konteksto ay nakalimutan na, at ang nakasulat na lamang ang natitira. Ang isang mahusay na README (panimulang dokumento na nagpapaliwanag kung ano ang isang proyekto at kung paano i-install at patakbuhin ito), mga paliwanag na komento ng code at isang napapanahong dokumentasyon ng API (isang sanggunian na nagpapaliwanag kung paano gumamit ng isang interface) ay direktang tumutukoy sa bilis ng isang koponan. Ang AI ay tumatagal ng maraming "pagkapagod sa pagsusulat" mula sa dokumentasyon — ngunit ito ay may kasamang bitag: Ang AI ay maaaring magpahiwatig mula sa code kung ano ang ginagawa nito, ngunit kadalasan ay hindi alam kung bakit ito ginagawa sa ganoong paraan.
Sa unit na ito, matututunan mo kung paano gumawa ng README, komento ng code, docstring (block ng komento na nakasulat sa bawat function/class), dokumento ng API at changelog gamit ang AI; at kung paano mapangalagaan ng tao ang pinakamahalagang bahagi ng dokumentasyon: ang "bakit."
Pagkakaiba sa pagitan ng "Ano" at "Bakit"
Mayroong dalawang layer ng dokumentasyon. Ang una ay kung ano/paano: "ang function na ito ay nag-uuri ng isang listahan", "patakbuhin ang command na ito upang mai-install". Ang mga ito ay maaaring makuha mula sa code at istraktura; Ang AI ay mahusay dito. Pangalawa, bakit: "bakit ginawa naming asynchronous ang serbisyong ito sa halip na magkasabay", "bakit 30 segundo ang halaga ng limitasyong ito", "bakit namin pinili ang library na ito kaysa sa iba." Ang mga ito ay hindi nakasulat sa code; Ito ay produkto ng mga desisyon sa disenyo, mga hadlang, at nakaraang sakit.
Hindi alam ng AI ang "bakit"; Sa pinakamainam, ito ay bumubuo ng isang makatwirang hula—na mapanganib, dahil ang isang maling dahilan ay mas masahol kaysa sa walang dahilan. Kaya malinaw ang dibisyon ng paggawa: Ang AI ay nag-draft ng "ano/paano," idinagdag mo ang "bakit." Ang pinakamahalagang komento ay ang nagsasabi kung ano ang hindi masasabi ng code.
Tip: Huwag ulitin gamit ang isang komento kung ano ang malinaw na sinasabi ng code mismo (tulad ng i = i + 1 // dagdagan ang i ng isa). Minsan ang AI ay gumagawa ng mga labis na komento; Tanggalin ang mga ito at italaga ang iyong lakas sa mga komentong "bakit".
Hakbang sa Hakbang: Pagbuo ng Dokumentasyon gamit ang AI
- Tukuyin ang target na madla. "Isang developer na nagsisimula pa lang," "ang panlabas na team na gagamit ng API na ito," "the future me" — ang audience ang nagtatakda ng tono para sa wika at lalim.
- Ibigay ang pinagmulan. Idagdag ang nauugnay na code, umiiral na README, halimbawa ng paggamit sa prompt. Ang isang hindi pinagkunan na dokumento ay isang imbitasyon sa katha.
- Istraktura ng pagpapataw. Mga karaniwang seksyon para sa README (Layunin, Pag-install, Paggamit, Configuration, Kontribusyon), format ng proyekto para sa docstring.
- Markahan ang mga puwang na "bakit". Hilingin sa AI na markahan ang mga desisyon kung saan hindi nito alam ang katwiran bilang "isang 'bakit' tala ay kinakailangan dito"; Pagkatapos ay punan mo ang mga blangko.
- I-verify. Talagang patakbuhin ang mga hakbang sa pag-install; subukan ang sample code. Ang README na hindi gumagana ay mas masahol pa kaysa sa walang README.
Tatlong Mini Case
Case 1 — Pinabilis ng README ang onboarding. Nawawala ang README ng isang open source tool; Nahirapan ang mga bagong kontribyutor sa pag-install sa average na 2 oras. Ibinigay ng team ang mga script sa pag-install at package.json sa AI at nag-draft ng isang structured na README, pagkatapos ay pinatakbo mismo ang mga hakbang sa isang malinis na makina at idinagdag ang dalawang nawawalang dependency. Bumaba sa average na 25 minuto ang oras ng pag-install para sa mga kasunod na nag-aambag.
Kaso 2 — Ang ginawang bitag na “bakit”. Humiling ang isang developer sa AI ng komento sa tabi ng value ng timeout (timeout=30). Sumulat ang AI ng isang makatwiran ngunit hindi tamang katwiran "upang tiisin ang mataas na latency ng network"; ang tunay na dahilan ay ang kontraktwal na 30 segundong limitasyon ng downstream na serbisyo. Ang maling interpretasyon ay humantong sa isang kasunod na developer na hindi kinakailangang taasan ang halaga, na humahantong sa isang insidente. Aralin: dapat i-verify ng may-ari ng code ang katwiran.
Kaso 3 — Ang pamantayan ng Docstring ay naging awtomatiko. Ang isang auxiliary module na may 40 function ay walang mga docstring. Binigyan ang AI ng format ng proyekto (estilo ng Google) at gumawa ng parameter, pagbabalik at mga paglalarawan ng exception para sa bawat function; Sinuri ng developer ang mga ito at inayos ang ilang maling uri ng mga deklarasyon. Ang pagdodokumento ng 40 function ay bumaba mula halos kalahating araw hanggang isang oras.
Apat na Nakokopyang Template
Nakabalangkas na README draft:
Target na madla: {{e.g. bagong contributor}}. Sumulat ng draft na README batay sa mga file sa ibaba. Mga Seksyon: Layunin, Mga Tampok, Mga Kinakailangan, Pag-install, Operasyon, Configuration, Pagsubok, Kontribusyon. I-extract ang pag-install/pagpapatakbo ng mga utos mula sa aktwal na mga file; ANGKOP. Markahan ng "[VERIFY]" ang mga lugar na hindi ka sigurado. Pinagmulan: {{package.json / scripts / sample code}}
Sanggunian ng Docstring/API:
Sumulat ng docstring sa mga function na ito sa {{project style: Google/NumPy/JSDoc}} na format: maikling buod, mga parameter (uri + kahulugan), return, mga exception na itinapon, 1 maikling halimbawa. Huwag ulitin kung ano ang MALIWANAG na sinasabi ng code. Markahan ang mga desisyon sa disenyo na nangangailangan ng "bakit" bilang "[BAKIT KAILANGAN]", huwag magsulat ng gawa-gawang katwiran.{{code}}
Alisin ang mga puwang para sa komentong "bakit":
Sa code na ito, maaaring magtanong ang susunod na developer ng "bakit ganito?" (mga magic number, hindi pangkaraniwang desisyon, mga solusyon). Magbigay ng komento SKELETON para sa bawat isa, ngunit iwanang BLANKO ang katwiran; Pupunan ko ang katwiran.{{code}}
Changelog/PR na pahayag:
Sumulat ng {{changelog entry / PR description}} mula sa diff sa ibaba. Format: Ano ang nagbago (sa user language), Bakit (isyu: {{...}}), Breaking change (kung mayroon), Nasubukan na ba ito. Isaayos ang teknikal na jargon sa target na madla.{{diff}}
Mahinang prompt / Malakas na prompt
Mahina: "Sumulat ng README para sa proyektong ito."
Malakas: "Target na madla: isang developer ang nag-clone ng repo na ito sa unang pagkakataon. Batay sa naka-attach na package.json, docker-compose.yml at scripts/ folder, magsulat ng draft README na may mga Layunin, Mga Kinakailangan, Pag-install, Operasyon, Pagsubok, Kontribusyon na mga seksyon. I-extract ang mga command mula sa mga file na ito, huwag gawin ang mga ito; markahan kung saan ka hindi sigurado ng [VERIFY]."
Ang malakas na bersyon ay nagbibigay sa madla, ang pinagmulan, ang istraktura, at ang "gawin ito, markahan ito" na panuntunan; upang ang dokumento ay batay sa mga totoong file at ang mga lugar na ibe-verify ay malinaw na nakikita.
Uri ng dokumento
Magaling ang AI
Nagdaragdag/nagbe-verify ang tao
Pag-install ng README
balangkas ng hakbang
Patakbuhin ang mga hakbang at kumpirmahin
Docstring/API
Istraktura, parameter, uri
Tamang uri at "bakit"
Komento ng code
"Anong ginagawa niya" buod
"Bakit ito" katwiran
Changelog/PR
unang draft
Epekto at katumpakan
Architectural decision (ADR)
kalansay
Mga tunay na desisyon at kompromiso
Ang Dokumentasyon ay Nangangailangan ng Pagpapanatili
Ang pinaka-mapanganib na aspeto ng isang dokumento ay kapag mukhang totoo ito kahit na ito ay mali. Kapag nagbago ang code at hindi na-update ang dokumento, aktibong nililinlang nito ang mambabasa. Pinapadali ng AI ang pag-update: mag-isyu ng diff at magtanong "aling bahagi ng dokumento ang naaapektuhan ng pagbabagong ito?" maaari kang magtanong. Ngunit ang proseso ang nagsisiguro ng pagiging napapanahon — gawing bahagi ng pagbabago ng code ang pag-update ng dokumentasyon (ang pamantayan sa pagtanggap ng PR). Bumibilis ang AI; Ang pangkat ay bumubuo ng disiplina.
Babala: Huwag mag-publish nang hindi bini-verify ang mga hakbang sa pag-install sa isang README. Ang isang "marahil gumagana" na dokumento ay maaaring sumira sa unang araw ng isang bagong developer at masira ang tiwala. Patakbuhin ang mga hakbang sa iyong sarili sa isang malinis na kapaligiran.
Mga karaniwang pagkakamali
- Pagkuha ng "bakit" upang magkasya sa AI. Ang maling pagbibigay-katwiran ay mas masahol pa sa walang katwiran; Dapat isulat ng may-ari ng code ang dahilan ng disenyo.
- Hindi na-verify ang mga hakbang sa pag-install. Ang README na hindi gumagana ay sumisira sa tiwala.
- Hindi kinakailangang komento na inuulit ang code. Gumagawa ito ng ingay, na ikinukubli ang totoong "bakit" na mga interpretasyon.
- Hindi tinukoy ang target na madla. Ang isang dokumento na hindi malinaw kung kanino ito isinulat ay walang silbi sa baguhan o sa eksperto.
- Paghihiwalay sa pag-update mula sa proseso. Kung ang dokumento ay hindi na-update gamit ang code, mabilis itong nagiging mapanlinlang.
Sa buod
Inaalis ng AI ang malaking bahagi ng mekanikal na pasanin mula sa dokumentasyon: mabilis na mga draft README, docstring, sanggunian ng API, changelog at mga paglalarawan ng PR. Ngunit hindi nito malalaman ang "bakit", na siyang pinakamahalagang layer, at ito ay mapanganib na gawin ito. Malinaw ang dibisyon ng paggawa: Ang AI ay gumagawa ng "ano/paano," idinagdag mo ang "bakit." Tukuyin ang madla, magbigay ng mga mapagkukunan, magpataw ng istraktura, markahan ang mga lugar upang magkasya, at i-verify ang bawat hakbang sa pag-install sa pamamagitan ng pagpapatakbo nito mismo. Gawing mahalagang bahagi ng pagbabago ng code ang dokumentasyon.
Gawain ng aplikasyon
Pumili ng module o maliit na proyekto na ang dokumentasyon ay nawawala o hindi na napapanahon. Bumuo muna ng outline mula sa AI gamit ang template na "structured README draft" (o docstring); Tiyaking ibigay ang pinagmulan at target na madla. Pagkatapos ay dumaan sa bawat punto kung saan minarkahan ng AI ang [VERIFY] o [WHY NEEDED]: aktwal na patakbuhin ang mga hakbang sa pag-setup at punan ang disenyo na "bakit" gamit ang iyong sariling kaalaman. Tandaan kung gaano karaming mga hakbang ang kailangang ayusin at kung gaano karaming "bakit" ang iyong idinagdag.
checklist
- [ ] Sa dokumentasyon, nakikilala ko ang mga layer na "ano/paano" at "bakit".
- [ ] Hindi ko ginagawa ang AI na "bakit", ako mismo ang nagdagdag nito.
- [ ] Binibigyan ko ng prompt ang target na madla at ang aktwal na source file.
- [ ] Bine-verify ko ang [VERIFY] na mga puntos na minarkahan ng AI sa pamamagitan ng personal na pagpapatupad ng mga ito.
- [ ] Tinatanggal ko ang mga hindi kinakailangang komento na inuulit ang code.
- [ ] Ginagawa kong bahagi ng pagbabago ng code ang pag-update ng dokumentasyon.