Gevinster:
- Evne til at producere README, docstring og changelog-udkast baseret på målgruppe og kilde med AI
- Evne til at adskille 'hvad/hvordan' og 'hvorfor' lagene i dokumentationen og tilføje 'hvorfor' som menneske
- Bekræftelse af installationstrinnene ved personligt at køre dem og gøre dokumentet til en del af kodeændringen
Den hyppigst forsømte, men længst holdbare del af software er dokumentation. Koden er læsbar selv efter måneder; Personen, der skrev det, er væk, konteksten er glemt, og kun det, der er skrevet, er tilbage. En god README (introduktionsdokument, der forklarer, hvad et projekt er, og hvordan man installerer og kører det), forklarende kodekommentarer og en opdateret API-dokumentation (en reference, der forklarer, hvordan man bruger en grænseflade) bestemmer direkte hastigheden for et team. AI tager meget af "skrivetrætheden" ud af dokumentationen - men det kommer med en fælde: AI kan udlede fra kode, hvad den gør, men kan ofte ikke vide, hvorfor det er gjort på den måde.
I denne enhed lærer du, hvordan du producerer README, kodekommentar, docstring (kommentarblok skrevet pr. funktion/klasse), API-dokument og changelog med AI; og hvordan man menneskeligt bevarer den mest værdifulde del af dokumentationen: "hvorfor."
Forskellen mellem "Hvad" og "Hvorfor"
Der er to lag af dokumentation. Den første er hvad/hvordan: "denne funktion sorterer en liste", "kør denne kommando for at installere". Disse kan uddrages fra koden og strukturen; AI udmærker sig her. For det andet hvorfor: "hvorfor gjorde vi denne tjeneste asynkron i stedet for synkron", "hvorfor er denne grænseværdi 30 sekunder", "hvorfor valgte vi dette bibliotek frem for det andet". Disse er ikke skrevet i koden; Det er et produkt af designbeslutninger, begrænsninger og tidligere smerte.
AI ved ikke "hvorfor"; I bedste fald gør det et rimeligt gæt - hvilket er farligt, fordi en forkert grund er værre end ingen grund overhovedet. Så arbejdsdelingen er klar: AI udarbejder "hvad/hvordan", du tilføjer "hvorfor." Den mest værdifulde kommentar er den, der siger, hvad koden ikke kan sige.
Tip: Gentag ikke med en kommentar, hvad koden selv tydeligt siger (f.eks. i = i + 1 // øge i med én). AI producerer nogle gange sådanne overflødige kommentarer; Fjern dem og brug din energi til "hvorfor" kommentarer.
Trin for trin: Dokumentationsgenerering med AI
- Angiv målgruppen. "En udvikler, der lige er startet", "det eksterne team, der vil bruge denne API", "det fremtidige mig" - publikum sætter tonen for sprog og dybde.
- Giv kilden. Tilføj den relevante kode, eksisterende README, eksempelbrug til prompten. Et unsourcet dokument er en invitation til fremstilling.
- Pålægsstruktur. Standardsektioner for README (Formål, Installation, Brug, Konfiguration, Bidrag), projektformat for docstring.
- Marker "hvorfor" mellemrum. Bed AI om at markere beslutninger, som den ikke kender begrundelsen for, som "en 'hvorfor' note er påkrævet her"; Så udfylder du de tomme felter.
- Verificere. Kør faktisk installationstrinnene; prøv prøvekoden. En README, der ikke virker, er værre end slet ingen README.
Tre mini etuier
Case 1 — README accelereret onboarding. Et open source-værktøjs README manglede; Nye bidragydere kæmpede med installationen i gennemsnitligt 2 timer. Holdet gav installationsscripts og package.json til AI og udarbejdede et struktureret README, kørte derefter selve trinene på en ren maskine og tilføjede de to manglende afhængigheder. Installationstiden for efterfølgende bidragydere faldt til et gennemsnit på 25 minutter.
Case 2 — Den opdigtede "hvorfor"-fælde. En udvikler bad AI om en kommentar ved siden af en timeoutværdi (timeout=30). AI skrev en rimelig, men forkert begrundelse "for at tolerere høj netværksforsinkelse"; den egentlige årsag var en downstream-tjenestes kontraktmæssige grænse på 30 sekunder. Fejlfortolkningen fik en efterfølgende udvikler til at øge værdien unødigt, hvilket førte til en hændelse. Lektion: Kodeejeren skal bekræfte begrundelsen.
Case 3 — Docstring-standarden er blevet automatiseret. Et hjælpemodul med 40 funktioner havde ingen docstrings. AI'en fik projektformatet (Google-stil) og producerede parameter-, retur- og undtagelsesbeskrivelser for hver funktion; Udvikleren gennemgik disse og rettede nogle få forkerte typeerklæringer. Dokumentation af 40 funktioner gik ned fra cirka en halv dag til en time.
Fire kopierbare skabeloner
Struktureret README-udkast:
Målgruppe: {{f.eks. ny bidragyder}}.Skriv et udkast til README baseret på filerne nedenfor. Sektioner: Formål, Funktioner, Krav, Installation, Drift, Konfiguration, Test, Bidrag. Udpak installation/kørende kommandoer fra faktiske filer; MONTERING. Marker de steder, du ikke er sikker på, med "[VERIFY]". Kilde: {{package.json / scripts / eksempelkode}}
Docstring/API reference:
Skriv docstring til disse funktioner i {{projektstil: Google/NumPy/JSDoc}}-format: kort resumé, parametre (type + betydning), retur, kastede undtagelser, 1 kort eksempel. Gentag ikke, hvad koden KLART siger. Markér designbeslutninger, der kræver "hvorfor" som "[HVORFOR NØDVENDIG]", skriv ikke en opdigtet begrundelse.{{kode}}
Fjern mellemrum for "hvorfor" kommentar:
I denne kode kan den næste udvikler spørge "hvorfor er det sådan?" (magiske tal, usædvanlige beslutninger, løsninger). Giv en kommentar SKELETON til hver, men lad begrundelsen være BLANK; Jeg udfylder begrundelsen.{{code}}
Ændringslog/PR-erklæring:
Skriv en {{changelog entry / PR description}} fra forskellen nedenfor. Format: Hvad er ændret (på brugersprog), Hvorfor (problem: {{...}}), Brydende ændring (hvis nogen), Er det blevet testet. Tilpas teknisk jargon til målgruppen.{{diff}}
Svag prompt / Stærk prompt
Svag: "Skriv en README til dette projekt."
Stærk: "Målgruppe: en udvikler, der kloner denne repo for første gang. Baseret på den vedhæftede package.json, docker-compose.yml og scripts/ folder, skriv et udkast til README med formål, krav, installation, drift, test, bidrag sektioner. Udpak kommandoerne fra disse filer, gør dem ikke op]."
Den stærke version giver publikum, kilden, strukturen og "gør det, markér det"-reglen; så dokumentet er baseret på rigtige filer, og de steder, der skal verificeres, er tydeligt synlige.
Dokumenttype
AI gør det godt
Menneske tilføjer/verificerer
README installation
trin omrids
Kør trinene og bekræft
Docstring/API
Struktur, parameter, type
Korrekt type og "hvorfor"
Kodekommentar
"Hvad han laver" resumé
"Hvorfor er dette" begrundelse
Ændringslog/PR
første udkast
Effekt og nøjagtighed
Arkitekturbeslutning (ADR)
skelet
Reelle beslutninger og kompromiser
Dokumentation kræver vedligeholdelse
Det farligste aspekt af et dokument er, når det virker sandt, selvom det er falsk. Når koden ændres, og dokumentet ikke opdateres, vildleder det aktivt læseren. AI gør det nemt at opdatere: udsted en diff og spørg "hvilke dele af dokumentet påvirker denne ændring?" kan du spørge. Men det er processen, der sikrer opdateringen — gør dokumentationsopdateringen til en del af kodeændringen (PR's acceptkriterium). AI accelererer; Holdet opbygger disciplin.
Forsigtig: Udgiv ikke uden at verificere installationstrinnene i en README. Et "formentlig arbejde" dokument kan ødelægge en ny udviklers første dag og udhule tilliden. Kør trinene selv i et rent miljø.
Almindelige fejl
- At få "hvorfor" til at passe til AI. Falsk begrundelse er værre end ingen begrundelse; Kodeejeren skal skrive designårsagen.
- Installationstrinene bekræftes ikke. README, der ikke virker, ødelægger tilliden.
- Unødvendig kommentar, der gentager koden. Det producerer støj, og slører reelle "hvorfor"-fortolkninger.
- Uden at angive målgruppen. Et dokument, der er uklart, til hvem det er skrevet, er til ingen nytte for hverken nybegynderen eller eksperten.
- Adskiller opdateringen fra processen. Hvis dokumentet ikke er opdateret med koden, bliver det hurtigt vildledende.
Sammenfattende
AI tager meget af den mekaniske byrde ud af dokumentation: hurtige udkast README, docstring, API-reference, changelog og PR-beskrivelser. Men den kan ikke vide "hvorfor", som er det mest værdifulde lag, og det er farligt at finde på det. Arbejdsdelingen er klar: AI producerer "hvad/hvordan", du tilføjer "hvorfor." Angiv målgruppen, giv ressourcer, påtving struktur, markér steder, der passer, og bekræft hvert installationstrin ved at køre det selv. Gør dokumentation til en integreret del af kodeændringen.
Ansøgningsopgave
Vælg et modul eller et lille projekt, hvis dokumentation mangler eller er forældet. Generer først en disposition fra AI med skabelonen "struktureret README draft" (eller docstring); Sørg for at give kilden og målgruppen. Gå derefter igennem hvert punkt, hvor AI har markeret [VERIFY] eller [HVORFOR NØDVENDIG]: kør faktisk opsætningstrinnene og udfyld designet "hvorfor" med din egen viden. Bemærk, hvor mange trin der skal rettes, og hvor mange "hvorfor" du tilføjede.
tjekliste
- [ ] I dokumentationen skelner jeg mellem lagene "hvad/hvordan" og "hvorfor".
- [ ] Jeg får ikke AI til at udgøre "hvorfor", jeg tilføjer det selv.
- [ ] Jeg giver prompten målgruppen og de faktiske kildefiler.
- [ ] Jeg verificerer [VERIFY]-punkterne markeret af AI'en ved personligt at udføre dem.
- [ ] Jeg fjerner unødvendige kommentarer, der gentager koden.
- [ ] Jeg gør dokumentationsopdateringen til en del af kodeændringen.