Dokumentatsiooni genereerimine koodist: mida tehisintellekt teeb õigesti ja mida valesti
Suuna mudel repositooriumile, palu abikeskust ja sa saad selle. See näeb välja valmis. Siis loed neljandat artiklit ja see räägib sinu klientidele PlanTier.PRO_LEGACY-st ja ekraanist aadressil /admin/impersonate.
Nii et kas tehisintellekt saab koodist dokumentatsiooni genereerida? Jah, ja mustandid on kasulikud. Tehisintellekt on hea kõigi funktsioonide leidmises, nuppude siltide täpses äratoomises ja ühtlase esimese versiooni koostamises. Otse mudelist välja tulles eksib ta aga usaldusväärselt kolmes asjas: ta lekitab sisemist žargooni, dokumenteerib ekraane, mida sinu kasutajad ei näe, ning kirjeldab koodi, mitte ülesannet, mida kasutaja täita püüab. Lahendus on mustandid töötavasse rakendusse ankurdada ja lasta inimesel kõik enne avaldamist üle vaadata.
Siin on, miks nii ja kuidas seda seadistada, et tulemus oleks väljastamist väärt.
Kaks väga erinevat “dokumentatsiooni koodist” liiki
Kui inimesed seda otsivad, mõtlevad nad kaht asja ja neid tasub lahus hoida.
Arendajate viitedokumentatsioon. API viited, SDK dokumentatsioon, funktsioonide signatuurid. See on enamasti lahendatud probleem ja see ei vaja tehisintellekti üldse. TypeDoc, Sphinx autodoc, Javadoc ja OpenAPI tööriistad nagu Swagger UI loevad sinu koodi või spetsifikatsiooni ning toodavad viitelehti deterministlikult. Need on igavad ja usaldusväärsed, mida viitedokumentatsioonilt ongi vaja.
Kasutajadokumentatsioon. Abikeskuse artiklid inimestele, kes ei näe kunagi sinu koodi: “kuidas ma oma arveid eksportin”, “kuidas ma meeskonnakaaslase lisan”. See on raske osa ja siin on tehisintellekti dokumentatsioonigeneraatorid nüüd tõeliselt kasulikud ja tõeliselt riskantsed.
See postitus räägib teisest liigist. Kui vajad README-faili või koodikommentaare, teeb sinu kodeerimisassistent seda juba piisavalt hästi.
Mida tehisintellekt teeb hästi, kui genereerib koodist kasutajadokumentatsiooni
Au, kellele au. Koodibaasi lugev mudel on mõne konkreetse töö juures parem kui inimene.
Ta leiab kõik
Inimesed kirjutavad dokumentatsiooni mälu põhjal ja mälu unustab funktsioone. CSV-import, mille keegi ehitas kaheksa kuud tagasi. Klaviatuuri kiirklahv. Seadistus, mis ilmub ainult meeskonnaplaanis. Mudel, mis loeb sinu marsruutide faili, navigatsioonikomponente ja vorme, toodab täieliku inventari ja see inventar üksi on harjutuse väärt. Enamikul abikeskustel on lüngad, millest keegi ei tea.
Ta saab täpsed sildid
Nupu tekst on koodis otse olemas: "Export CSV", "Send invite". Mudel tsiteerib seda täpselt, samas kui inimene kirjutab “klõpsa eksportimise nuppu” ja jätab lugeja ära arvama.
Ta märkab piiranguid ja reegleid
Valideerimisreeglid asuvad koodis. Projekti nime maksimaalne pikkus, failisuuruse piir, rollikontroll, mis nupu hallikaks muudab. Need on täpselt need detailid, mis tekitavad tugipiletid (“miks ma ei saa seda salvestada?”) ja täpselt need detailid, mida inimkirjutaja ei tea.
Mida tehisintellekt valesti teeb, kui genereerib koodist dokumentatsiooni
See on osa, mida enamik tööriistu oma kodulehele ei pane. Minu kogemuse järgi ilmnevad need ebaõnnestumisviisid peaaegu igas toores tehisintellekti mustandis.
1. Sisemine žargoon lekib läbi
Sinu kood ja sinu kasutajaliides kasutavad erinevaid sõnu. Tabel on workspaces, kasutajaliideses on “Team”. Enum on PlanTier.PRO_LEGACY, hinnalehel on “Pro”. Funktsiooni kutsuti sisemiselt aasta aega smartRouting, enne kui turundus selle “Auto-assign”-iks nimetas.
Mudel loeb koodi, nii et ta kasutab koodisõnu. Saad selliseid lauseid nagu “Loo uus workspace (org) lehel Teams”, mis on klientidele segadusttekitav ja ka vale. Hullem, see lekitab nimesid, mida sa ei kavatsenud kunagi avalikuks teha.
2. Ta dokumenteerib ekraane, mida sinu kasutajad ei näe
Mudel näeb marsruuti ja kirjutab sellele artikli. Tal pole aimugi, et:
/admin/*on sinu sisemine klienditoe tööriist- leht “Bulk import” on funktsioonilipu taga, mis on sisse lülitatud kolmel beetakontol
- seadistused “Teams” kuvatakse ainult Business-plaanis
- see vana sisseelamisvoog on surnud kood, mida keegi ei eemaldanud
Nii kirjutab ta abiartiklid neile kõigile. Parimal juhul lähevad kliendid otsima ekraane, mida neile ei eksisteeri, ja kirjutavad sulle. Halvimal juhul oled avaldanud oma tegevuskava või juhendi oma administraatori kasutaja-imiteerimise tööriista kohta.
3. Ta kirjeldab koodi, mitte kasutaja ülesannet
See on peen ja kõige sagedasem. Mudel selgitab, mida kood teeb, sest seda ta vaatabki. Kasutajad ei hooli sellest, mida kood teeb. Nad tahavad midagi korda saata.
Vasak versioon on täpne. See on ka kasutu inimesele, kelle raamatupidaja just küsis eelmise kvartali arveid. Parem versioon lähtub eesmärgist, kasutab ekraanil olevaid sõnu ja näitab, kuhu klõpsata. Diátaxise raamistik tõmbab selle joone hästi: juhend teenib eesmärki, viide kirjeldab masinavärki. Toored tehisintellekti mustandid kalduvad viite poole isegi siis, kui palusid juhendit.
4. Ta oletab enesekindlalt käitumist, mida kood ei otsusta
Paljud asjad, mida kasutajad kogevad, ei otsusta ainult kood. See, kas kinnituskiri tegelikult saadetakse, sõltub konfiguratsioonist. See, milline leht välja näeb, sõltub selles olevatest andmetest. Sinu tagasimaksepoliitika, klienditoe tööajad ja see, mis andmetega pärast tühistamist juhtub, ei ole tavaliselt repositooriumis üldse.
Mudel täidab need lüngad usutavate oletustega, mis on kirjutatud sama enesekindlas toonis nagu kõik muu. See on ohtlik osa: valed laused ei näe õigetest mingil moel erinevad välja.
Miks dokumentatsiooni ankurdamine töötavasse rakendusse loeb
Kood ütleb, mis võib olemas olla. Töötav rakendus näitab, mida kasutaja tegelikult näeb.
Kui genereerid dokumentatsiooni ainult koodist, dokumenteerid oma toote teooriat. Käivita rakendus, logi sisse tavalise kasutajana tavalisel plaanil ja enamik ülaltoodud probleeme kahaneb:
- Admini ja funktsioonilipu taga olevad ekraanid lihtsalt ei ilmu, nii et neid ei dokumenteerita.
- Ekraanipildil olevad sildid on sildid, mida kliendid näevad, mis püüab kinni žargooni.
- Kui artikkel ütleb “klõpsa Export CSV” ja ekraanipildil pole eksportimise nuppu, oled leidnud vea (dokumentatsioonis või tootes) enne klienti.
Seda saad ise teha brauseri automatiseerimise tööriistaga. Minimaalne Playwrighti skript, mis logib sisse demokasutajana ja jäädvustab artikli jaoks lehe, näeb välja selline:
// docs/capture/billing.spec.ts
import { test } from '@playwright/test';
test('capture billing page for the invoices article', async ({ page }) => {
await page.goto('http://localhost:3000/login');
await page.getByLabel('Email').fill('docs-demo@example.com');
await page.getByLabel('Password').fill(process.env.DOCS_DEMO_PASSWORD!);
await page.getByRole('button', { name: 'Sign in' }).click();
await page.goto('http://localhost:3000/settings/billing');
await page.screenshot({ path: 'docs/img/download-invoices-step-1.png' });
});
Playwrighti ekraanipiltide dokumentatsioon katab ainult elemendi ja kogu lehe jäädvustused. Raske osa ei ole skript, vaid päriselt välja nägevate seedandmete olemasolu ja sisselogimine, mis töötab CI-s. Kogu seadistuse käime läbi artiklis kuidas ekraanipilte automaatselt luua.
Miks inimese ülevaatus ikka ei ole valikuline
Isegi hea ankurdamise korral peab keegi, kes toodet tunneb, iga artikli enne avaldamist läbi lugema. Mitte silmi üle libistama. Läbi lugema.
Siin on kontrollnimekiri, mille ülevaatajale annaksin:
- Sõnad vastavad kasutajaliidesele. Iga funktsiooni nimi, nupp ja menüükirje on see, mida kliendid näevad, mitte see, mida insenerid nimetavad.
- Iga ekraan on kättesaadav. Klient plaanil, mida see artikkel sihib, jõuab sinna tegelikult. Plaanipõhised funktsioonid ütlevad seda.
- See algab ülesandest. Pealkiri on midagi, mida kasutaja otsingusse kirjutaks. Esimene samm on klõps, mitte kontekstilõik.
- Poliitikad on päris. Kõik, mis puudutab raha, andmeid, tühistamist või klienditoe tööaegu, tuleb sinult, mitte mudelilt.
- Midagi väljaandmata. Mitte ühtegi beetafunktsiooni, sisemist tööriista ega nime, mida turundus pole välja kuulutanud.
Korraliku mustandi ülevaatamine on palju kiirem kui tühjalt lehelt kirjutamine, mis ongi kogu mõte. Kuid just see samm muudab usutava mustandi dokumentatsiooniks, mille taha sa seisad. Kui jätad selle vahele, avaldad mudeli oletusi oma ettevõtte nime all.
DIY töövoog, mida saad oma kodeerimisassistendiga käivitada
Sul ei ole vaja pühendatud tehisintellekti dokumentatsioonigeneraatorit, et saada suurem osa kasust kätte. Cursori, Claude Code’i, Copiloti või sarnasega:
1. Palu inventari, mitte artikleid. Midagi sellist:
List every user-facing feature in this app. For each one give:
- the route or screen where a user finds it
- the exact button/menu labels involved
- any plan, role or feature-flag check guarding it
Do not write documentation yet.
2. Kärbi seda käsitsi. Kriipsuta maha admini marsruudid, sisemised tööriistad, lipu taga olevad beetad ja surnud kood. See võtab kümme minutit ja hoiab ära kõige hullemad ebaõnnestumised.
3. Anna talle sõnastik. Lühike nimekiri, mis seob koodi terminid kasutajaliidese terminitega (workspace → Team, PRO_LEGACY → Pro). Kleebi see igasse koostamise juhisesse.
4. Koosta üks ülesanne artikli kohta. Palu juhendit, mis on kirjutatud mittetehnilisele kasutajale, kasutades ainult inventari silte, algab eesmärgist ja märgistab iga lause, milles ta pole kindel, märgiga [CHECK].
5. Käi rakendus läbi ja tee ekraanipildid. Järgi iga artiklit ise. Paranda, mis on vale, lisa ekraanipildid.
6. Vaata üle ülaltoodud kontrollnimekirja järgi, siis avalda. Struktuuri poolest on artiklis kuidas kirjutada abikeskuse artikleid, mida inimesed päriselt kasutavad mall, mis siin hästi töötab.
DIY tee nõrkus on samm 7, mida veel ei eksisteeri: märkamine, kui järgmise nädala koodimuudatus muudab artikli kaksteist valeks. See on eraldi probleem, mida käsitleb kuidas dokumentatsiooni ajakohasena hoida.
Kuidas Ellie Docs seda käsitleb
Ehitasime Ellie Docsi ülaltoodud ebaõnnestumisviiside ümber, nii et siin on, kuidas see kokku läheb.
See loeb sinu repositooriumi ja kaardistab funktsioonid ning kasutajale suunatud ekraanid, seejärel koostab abikeskuse mustandi, mis on korraldatud selle järgi, mida kasutajad teevad.

See käivitab sinu rakenduse liivakastis ja jäädvustab sisseloginud toote tõelised ekraanipildid, mis paigutatakse artiklitesse. Iga artikkel näitab, millistel funktsioonidel see põhineb, nii et kui need funktsioonid koodis muutuvad, teab Ellie, et artikkel võib olla mõjutatud.

Iga ühendatud PR-i puhul kontrollib see, milliseid artikleid muudatus puudutab, ja pakub muudatusi välja diffina, mille sa kas aktsepteerid või lükkad tagasi. Kui see kirjutab sinu muudatuslogi ühendatud PR-idest, jätab see väljalaskmata kirjed väljaandmata või funktsioonilipu taga oleva töö kohta. Miski ei avaldu ise. Avaldad sina.

Ka see eksib vahel. See ei saa teada sinu poliitikaid ja valib aeg-ajalt koodisõna kasutajaliidese sõna asemel. Sellepärast läheb iga mustand ja iga soovitus sinu kaudu. Kui töötad rakendusega, mis on ehitatud tehisintellekti ehitajaga, käsitleb juhend vibe-coding’u rakenduse dokumenteerimiseks sealseid lisakeerukusi.
Mõned küsimused, mida inimesed esitavad
Kas on olemas tasuta tehisintellekti dokumentatsioonigeneraator? Sinu kodeerimisassistent pluss ülaltoodud DIY töövoog ei maksa midagi lisaks. Ellie Docsil on ka tasuta plaan ilma kaardita, kui eelistad, et ekraanipildid ja uuenduste jälgimine oleks sinu eest tehtud.
Kas tehisintellekt saab genereerida API dokumentatsiooni ilma OpenAPI spetsifikatsioonita? Saab, lugedes sinu marsruudikäsitlejaid. Kui sul on spetsifikatsioon juba olemas, kasuta standardseid tööriistu nagu Swagger UI või Redoc; see on deterministlik ja tasuta. Ellie Docs genereerib API viite koodist ilma spetsifikatsioonita oma Growth-plaanis, mis aitab, kui sa kunagi seda ei kirjutanud.
Kas peaksin laskma tehisintellektil dokumentatsiooni automaatselt avaldada? Ei. Lase tal mustandeid koostada ja ettepanekuid teha. Inimene, kes toodet tunneb, peaks heaks kiitma kõik, mida kliendid loevad, eriti kõik arvelduse või andmetega seotu.
Kas tehisintellekti kirjutatud dokumentatsioon on täpne? Nii täpne kui ankurdamine ja selle taga olev ülevaatus. Ainult koodist oota kasulikku mustandit enesekindlate vigadega. Töötavasse rakendusse ankurdatult ja toodet tundva inimese poolt üle vaadatuna võib see olla parem kui see, mida enamik meeskondi käsitsi kirjutab, peamiselt seetõttu, et see katab funktsioone, mille inimesed unustasid.
Kui tahad mustandeid, mis on ankurdatud sinu päris rakendusse, ekraanipiltide ja PR-ide kaupa soovitustega, mille sa heaks kiidad, proovi Ellie Docsi tasuta. Ühenda repositoorium ja vaata täna üle oma esimene koostatud abikeskus.