Câștiguri:
- Abilitatea de a produce schițe README, docstring și jurnal de modificări pe baza publicului țintă și a sursei cu AI
- Abilitatea de a separa straturile „ce/cum” și „de ce” în documentație și de a adăuga „de ce” ca om
- Verificarea pașilor de instalare, rulându-i personal și făcând ca documentul să facă parte din modificarea codului
Cea mai frecvent neglijată, dar cea mai durabilă parte a software-ului este documentația. Codul este lizibil chiar și după luni de zile; Persoana care a scris a dispărut, contextul este uitat și rămâne doar ceea ce a fost scris. Un README bun (document introductiv care explică ce este un proiect și cum să-l instalezi și să-l rulezi), comentarii explicative de cod și o documentație API actualizată (o referință care explică cum să folosești o interfață) determină direct viteza unei echipe. AI elimină o mare parte din „oboseala de scriere” din documentație – dar vine cu o capcană: AI poate deduce din cod ce face, dar adesea nu poate ști de ce se face așa.
În această unitate, veți învăța cum să produceți README, comentariu de cod, docstring (bloc de comentarii scris pe funcție/clasă), document API și jurnal de modificări cu AI; și cum să păstrați uman cea mai valoroasă parte a documentației: „de ce”.
Distincția între „Ce” și „De ce”
Există două straturi de documentare. Primul este ce/cum: „această funcție sortează o listă”, „execută această comandă pentru a instala”. Acestea pot fi extrase din cod și structură; AI excelează aici. În al doilea rând, de ce: „de ce am făcut acest serviciu mai degrabă asincron decât sincron”, „de ce această valoare limită este de 30 de secunde”, „de ce am ales această bibliotecă față de cealaltă”. Acestea nu sunt scrise în cod; Este produsul deciziilor de proiectare, constrângeri și dureri din trecut.
AI nu știe „de ce”; În cel mai bun caz, face o presupunere rezonabilă – ceea ce este periculos, deoarece un motiv greșit este mai rău decât niciun motiv. Deci diviziunea muncii este clară: AI redactează „ce/cum”, tu adaugi „de ce”. Cel mai valoros comentariu este cel care spune ceea ce codul nu poate spune.
Sfat: Nu repeta cu un comentariu ceea ce spune clar codul în sine (cum ar fi i = i + 1 // mărește i cu unu). AI produce uneori astfel de comentarii redundante; Eliminați-le și dedicați-vă energia comentariilor „de ce”.
Pas cu pas: Generarea documentației cu AI
- Specificați publicul țintă. „Un dezvoltator abia la început”, „echipa externă care va folosi acest API”, „eu viitorul” – publicul dă tonul pentru limbaj și profunzime.
- Dați sursa. Adăugați codul relevant, README existent, exemplu de utilizare la prompt. Un document fără surse este o invitație la fabricație.
- Structura de impunere. Secțiuni standard pentru README (scop, instalare, utilizare, configurare, contribuție), format de proiect pentru docstring.
- Marcați spațiile „de ce”. Cereți AI să marcheze deciziile pentru care nu cunoaște rațiunea ca „o notă „de ce” este necesară aici”; Apoi completați acele spații libere.
- Verifica. Rulați de fapt pașii de instalare; încercați exemplul de cod. Un README care nu funcționează este mai rău decât nici un README.
Trei mini carcase
Cazul 1 — README a accelerat integrarea. Lipsa README al unui instrument open source; Noii colaboratori s-au luptat cu instalarea timp de o medie de 2 ore. Echipa a dat script-urile de instalare și package.json AI și a elaborat un README structurat, apoi a rulat ei înșiși pașii pe o mașină curată și a adăugat cele două dependențe lipsă. Timpul de instalare pentru colaboratorii următori a scăzut la o medie de 25 de minute.
Cazul 2 – Capcana inventată „de ce”. Un dezvoltator a cerut AI un comentariu lângă o valoare de expirare (timeout=30). AI a scris o justificare rezonabilă, dar incorectă „pentru a tolera o latență mare a rețelei”; motivul real a fost limita contractuală de 30 de secunde a unui serviciu din aval. Interpretarea greșită l-a determinat pe un dezvoltator ulterior să mărească inutil valoarea, ducând la un incident. Lecție: proprietarul codului trebuie să verifice justificarea.
Cazul 3 — Standardul Docstring a devenit automatizat. Un modul auxiliar cu 40 de funcții nu avea docstrings. AI a primit formatul proiectului (stil Google) și a produs descrieri ale parametrilor, returnării și excepțiilor pentru fiecare funcție; Dezvoltatorul le-a revizuit și a remediat câteva declarații de tip incorecte. Documentarea a 40 de funcții a scăzut de la aproximativ o jumătate de zi la o oră.
Patru șabloane copiabile
Ciornă README structurată:
Publicul țintă: {{de ex. nou colaborator}}.Scrieți o schiță README pe baza fișierelor de mai jos. Secțiuni: Scop, Caracteristici, Cerințe, Instalare, Operare, Configurare, Testare, Contribuție. Extrageți comenzile de instalare/rularea din fișierele reale; MONTAJ. Marcați locurile de care nu sunteți sigur cu „[VERIFICAȚI]”. Sursa: {{package.json / scripts / exemplu de cod}}
Referință Docstring/API:
Scrieți docstring la aceste funcții în format {{stil proiect: Google/NumPy/JSDoc}}: rezumat scurt, parametri (tip + semnificație), returnare, excepții aruncate, 1 exemplu scurt. Nu repeta ce spune codul CLAR. Marcați deciziile de proiectare care necesită „de ce” drept „[DE CE NECESAR]”, nu scrieți o justificare fabricată.{{code}}
Eliminați spațiile pentru comentariul „de ce”:
În acest cod, următorul dezvoltator ar putea întreba „de ce este așa?” (numere magice, decizii neobișnuite, soluții alternative). Dați un comentariu SCHELET pentru fiecare, dar lăsați rațiunea GOL; Voi completa justificarea.{{code}}
Jurnalul modificărilor/Declarația PR:
Scrieți o {{registrare modificări / descriere PR}} din diferența de mai jos. Format: Ce s-a schimbat (în limba utilizatorului), De ce (problemă: {{...}}), Schimbare întreruptă (dacă există), A fost testat. Ajustați jargonul tehnic la publicul țintă.{{diff}}
Prompt slab / Prompt puternic
Slab: „Scrieți un README pentru acest proiect”.
Puternic: „Public țintă: un dezvoltator clonează acest depozit pentru prima dată. Pe baza pachetului atașat.json, docker-compose.yml și script-uri/ folder, scrieți o schiță README cu secțiuni Scop, Cerințe, Instalare, Operare, Testare, Contribuție. Extrageți comenzile din aceste fișiere, nu le creați oriunde.
Versiunea puternică oferă audienței, sursei, structura și regula „fă-l, marchează-l”; astfel încât documentul să se bazeze pe dosare reale, iar locurile de verificat să fie clar vizibile.
Tip document
AI se descurcă bine
Omul adaugă/verifică
Instalare README
schița pasului
Executați pașii și confirmați
Docstring/API
Structură, parametru, tip
Tipul corect și „de ce”
Comentariu cod
Rezumatul „Ce face”.
„De ce este aceasta” justificare
Jurnalul modificărilor/PR
primul proiect
Impact și precizie
Decizie arhitecturală (ADR)
schelet
Decizii reale și compromisuri
Documentația necesită întreținere
Cel mai periculos aspect al unui document este atunci când pare adevărat, chiar dacă este fals. Când codul se modifică și documentul nu este actualizat, acesta induce în eroare în mod activ cititorul. AI ușurează actualizarea: emiteți o diferență și întrebați „ce părți ale documentului afectează această modificare?” poți întreba. Însă procesul este cel care asigură actualitatea - faceți ca actualizarea documentației să facă parte din modificarea codului (criteriul de acceptare al PR). AI accelerează; Echipa construiește disciplină.
Atenție: Nu publicați fără a verifica pașii de instalare într-un README. Un document „probabil de lucru” poate strica prima zi a unui nou dezvoltator și poate eroda încrederea. Rulați singur pașii într-un mediu curat.
Greșeli comune
- Obținerea „de ce” pentru a se potrivi AI. Justificarea falsă este mai rea decât nicio justificare; Proprietarul codului ar trebui să scrie motivul proiectării.
- Nu se verifică etapele de instalare. README care nu funcționează distruge încrederea.
- Comentariu inutil care repetă codul. Produce zgomot, ascunzând interpretările reale ale „de ce”.
- Nu se specifică publicul țintă. Un document care nu este clar cui este scris nu este de nici un folos nici pentru novice, nici pentru expert.
- Separarea actualizării de proces. Dacă documentul nu este actualizat cu codul, acesta devine rapid înșelător.
Pe scurt
AI elimină o mare parte din sarcina mecanică a documentației: schițe rapide README, docstring, referință API, jurnalul de modificări și descrieri PR. Dar nu poate cunoaște „de ce”, care este cel mai valoros strat și este periculos să-l alcătuiești. Diviziunea muncii este clară: AI produce „ce/cum”, adăugați „de ce”. Specificați publicul, furnizați resurse, impuneți o structură, marcați locurile potrivite și verificați fiecare pas de instalare executându-l singur. Faceți din documentație o parte integrantă a modificării codului.
Sarcina de aplicare
Alegeți un modul sau un proiect mic a cărui documentație lipsește sau este învechită. Mai întâi generați o schiță din AI cu șablonul „schiță structurată README” (sau docstring); Asigurați-vă că oferiți publicul sursă și țintă. Apoi treceți prin fiecare punct în care AI a marcat [VERIFICARE] sau [DE CE ESTE NEVOIE]: rulați de fapt pașii de configurare și completați „de ce” de proiectare cu propriile cunoștințe. Rețineți câți pași trebuie remediați și câți „de ce” ați adăugat.
lista de verificare
- [ ] În documentație, disting straturile „ce/cum” și „de ce”.
- [ ] Nu fac ca AI-ul să compună „de ce”, îl adaug eu însumi.
- [ ] Dau promptului publicul țintă și fișierele sursă reale.
- [ ] Verific punctele [VERIFICARE] marcate de AI executându-le personal.
- [ ] Elimin comentariile inutile care repetă codul.
- [ ] Fac actualizarea documentației parte a modificării codului.