Gevinster:
- Evne til å produsere README-, docstring- og endringsloggutkast basert på målgruppe og kilde med AI
- Evne til å skille "hva/hvordan" og "hvorfor"-lagene i dokumentasjonen og legge til "hvorfor" som menneske
- Bekrefte installasjonstrinnene ved å kjøre dem personlig og gjøre dokumentet til en del av kodeendringen
Den mest forsømte, men lengst varige delen av programvaren er dokumentasjon. Koden er lesbar selv etter måneder; Den som skrev den er borte, konteksten er glemt, og bare det som ble skrevet gjenstår. En god README (introduksjonsdokument som forklarer hva et prosjekt er og hvordan man installerer og kjører det), forklarende kodekommentarer og en oppdatert API-dokumentasjon (en referanse som forklarer hvordan man bruker et grensesnitt) bestemmer direkte hastigheten til et team. AI tar mye av "skrivetrøttheten" ut av dokumentasjon - men det kommer med en felle: AI kan utlede fra kode hva den gjør, men kan ofte ikke vite hvorfor det er gjort på den måten.
I denne enheten lærer du hvordan du produserer README, kodekommentar, docstring (kommentarblokk skrevet per funksjon/klasse), API-dokument og endringslogg med AI; og hvordan man menneskelig kan bevare den mest verdifulle delen av dokumentasjonen: "hvorfor."
Skille mellom "Hva" og "Hvorfor"
Det er to lag med dokumentasjon. Den første er hva/hvordan: "denne funksjonen sorterer en liste", "kjør denne kommandoen for å installere". Disse kan trekkes ut fra koden og strukturen; AI utmerker seg her. For det andre, hvorfor: "hvorfor gjorde vi denne tjenesten asynkron i stedet for synkron", "hvorfor er denne grenseverdien 30 sekunder", "hvorfor valgte vi dette biblioteket fremfor det andre". Disse er ikke skrevet i koden; Det er et produkt av designbeslutninger, begrensninger og tidligere smerte.
AI vet ikke "hvorfor"; I beste fall utgjør det en rimelig gjetning – noe som er farlig, fordi en feil grunn er verre enn ingen grunn i det hele tatt. Så arbeidsdelingen er klar: AI utarbeider «hva/hvordan», du legger til «hvorfor». Den mest verdifulle kommentaren er den som sier det koden ikke kan si.
Tips: Ikke gjenta med en kommentar hva koden selv sier tydelig (som i = i + 1 // øke i med én). AI produserer noen ganger slike overflødige kommentarer; Eliminer dem og vie energien din til "hvorfor"-kommentarer.
Trinn for trinn: Dokumentasjonsgenerering med AI
- Spesifiser målgruppen. «En utvikler som nettopp har begynt», «det eksterne teamet som skal bruke denne APIen», «den fremtidige meg» – publikum setter tonen for språk og dybde.
- Gi kilden. Legg til den relevante koden, eksisterende README, eksempelbruk i ledeteksten. Et ukildedokument er en invitasjon til fabrikasjon.
- Påleggsstruktur. Standardseksjoner for README (Purpose, Installation, Usage, Configuration, Contribution), prosjektformat for docstring.
- Merk "hvorfor"-mellomrommene. Be AI om å merke avgjørelser som den ikke kjenner begrunnelsen for som "en 'hvorfor'-notat er nødvendig her"; Så fyller du ut de tomme feltene.
- Verifisere. Kjør faktisk installasjonstrinnene; prøv eksempelkoden. En README som ikke fungerer er verre enn ingen README i det hele tatt.
Tre minivesker
Tilfelle 1 – README akselerert onboarding. README-verktøyet for åpen kildekode manglet; Nye bidragsytere slet med installasjonen i gjennomsnitt 2 timer. Teamet ga installasjonsskriptene og package.json til AI og utarbeidet en strukturert README, kjørte deretter trinnene selv på en ren maskin og la til de to manglende avhengighetene. Installasjonstiden for påfølgende bidragsytere gikk ned til et gjennomsnitt på 25 minutter.
Tilfelle 2 - Den oppdiktede "hvorfor"-fellen. En utvikler ba AI om en kommentar ved siden av en tidsavbruddsverdi (timeout=30). AI skrev en rimelig, men feil begrunnelse "for å tolerere høy nettverksforsinkelse"; den virkelige årsaken var en nedstrømstjenestes kontraktuelle 30-sekunders grense. Feiltolkningen førte til at en påfølgende utvikler økte verdien unødvendig, noe som førte til en hendelse. Leksjon: Kodeeieren må bekrefte begrunnelsen.
Tilfelle 3 – Docstring-standarden har blitt automatisert. En hjelpemodul med 40 funksjoner hadde ingen docstrings. AI fikk prosjektformatet (Google-stil) og produserte parameter-, retur- og unntaksbeskrivelser for hver funksjon; Utvikleren gjennomgikk disse og fikset noen feil typedeklarasjoner. Å dokumentere 40 funksjoner gikk ned fra omtrent en halv dag til en time.
Fire kopierbare maler
Strukturert README-utkast:
Målgruppe: {{f.eks. ny bidragsyter}}.Skriv et utkast til README basert på filene nedenfor. Seksjoner: Formål, Funksjoner, Krav, Installasjon, Drift, Konfigurasjon, Testing, Bidrag. Pakk ut installasjons-/kjørekommandoer fra faktiske filer; PASSER. Merk stedene du ikke er sikker på med "[VERIFY]". Kilde: {{package.json / scripts / sample code}}
Docstring/API-referanse:
Skriv docstring til disse funksjonene i {{prosjektstil: Google/NumPy/JSDoc}}-format: kort sammendrag, parametere (type + betydning), retur, kastet unntak, 1 kort eksempel. Ikke gjenta hva koden TYDELIG sier. Merk designbeslutninger som krever "hvorfor" som "[HVORFOR NØDVENDIG]", ikke skriv en oppdiktet begrunnelse.{{kode}}
Fjern mellomrom for "hvorfor"-kommentaren:
I denne koden kan neste utvikler spørre "hvorfor er det slik?" (magiske tall, uvanlige avgjørelser, løsninger). Gi en kommentar SKELETT for hver, men la begrunnelsen stå BLANK; Jeg fyller ut begrunnelsen.{{code}}
Endringslogg/PR-erklæring:
Skriv en {{changelog entry / PR description}} fra diff nedenfor. Format: Hva endret (på brukerspråk), Hvorfor (problem: {{...}}), Brytende endring (hvis noen), Har den blitt testet. Tilpass teknisk sjargong til målgruppen.{{diff}}
Svak forespørsel / Sterk forespørsel
Svak: "Skriv en README for dette prosjektet."
Strong: "Målgruppe: en utvikler som kloner denne repoen for første gang. Basert på vedlagte package.json, docker-compose.yml og scripts/ folder, skriv et utkast README med Formål, Krav, Installasjon, Drift, Testing, Bidrag seksjoner. Pakk ut kommandoene fra disse filene, ikke finn dem opp]; merk hvor som helst du ikke er sikker."
Den sterke versjonen gir publikum, kilden, strukturen og regelen «lag det, merk det»; slik at dokumentet er basert på ekte filer og stedene som skal verifiseres er godt synlige.
Dokumenttype
AI gjør det bra
Human legger til/verifiserer
README installasjon
trinn omriss
Kjør trinnene og bekreft
Docstring/API
Struktur, parameter, type
Riktig type og "hvorfor"
Kodekommentar
"Hva han gjør" oppsummering
"Hvorfor er dette" begrunnelse
Endringslogg/PR
første utkast
Effekt og nøyaktighet
Arkitekturvedtak (ADR)
skjelett
Reelle beslutninger og kompromisser
Dokumentasjon krever vedlikehold
Det farligste aspektet ved et dokument er når det fremstår som sant selv om det er usant. Når koden endres og dokumentet ikke er oppdatert, villeder det aktivt leseren. AI gjør oppdateringen enkel: utsted en diff og spør "hvilke deler av dokumentet påvirker denne endringen?" kan du spørre. Men det er prosessen som sikrer oppdatering – gjør dokumentasjonsoppdateringen til en del av kodeendringen (PRs akseptkriterium). AI akselererer; Teamet bygger disiplin.
Forsiktig: Ikke publiser uten å bekrefte installasjonstrinnene i en README. Et «sannsynligvis arbeid»-dokument kan ødelegge en ny utviklers første dag og tære på tilliten. Kjør trinnene selv i et rent miljø.
Vanlige feil
- Få "hvorfor" til å passe til AI. Falsk begrunnelse er verre enn ingen begrunnelse; Kodeeieren bør skrive designårsaken.
- Verifiserer ikke installasjonstrinnene. README som ikke fungerer ødelegger tillit.
- Unødvendig kommentar som gjentar koden. Den produserer støy og skjuler virkelige "hvorfor"-tolkninger.
- Spesifiserer ikke målgruppen. Et dokument som er uklart til hvem det er skrevet, er til ingen nytte for verken nybegynneren eller eksperten.
- Skiller oppdateringen fra prosessen. Hvis dokumentet ikke er oppdatert med koden, blir det raskt misvisende.
Oppsummert
AI tar mye av den mekaniske byrden ut av dokumentasjon: raske utkast README, docstring, API-referanse, endringslogg og PR-beskrivelser. Men den kan ikke vite "hvorfor", som er det mest verdifulle laget, og det er farlig å finne på det. Arbeidsdelingen er klar: AI produserer "hva/hvordan", du legger til "hvorfor." Spesifiser publikum, oppgi ressurser, pålegg struktur, merk steder som passer, og bekreft hvert installasjonstrinn ved å kjøre det selv. Gjør dokumentasjon til en integrert del av kodeendringen.
Søknadsoppgave
Velg en modul eller et lite prosjekt hvis dokumentasjon mangler eller er utdatert. Generer først en disposisjon fra AI med malen "strukturert README draft" (eller docstring); Sørg for å oppgi kilden og målgruppen. Gå deretter gjennom hvert punkt der AI har merket [VERIFY] eller [HVORFOR NEEDED]: kjør faktisk oppsettstrinnene og fyll ut designet "hvorfor" med din egen kunnskap. Legg merke til hvor mange trinn som må fikses og hvor mange "hvorfor" du har lagt til.
sjekkliste
- [ ] I dokumentasjonen skiller jeg "hva/hvordan" og "hvorfor"-lagene.
- [ ] Jeg får ikke AI til å utgjøre "hvorfor", jeg legger det til selv.
- [ ] Jeg gir ledeteksten målgruppen og de faktiske kildefilene.
- [ ] Jeg bekrefter [VERIFY]-punktene merket av AI-en ved personlig å utføre dem.
- [ ] Jeg eliminerer unødvendige kommentarer som gjentar koden.
- [ ] Jeg gjør dokumentasjonsoppdateringen til en del av kodeendringen.