Dokumentacija je dio proizvoda

Mnogi timovi još uvijek govore o dokumentaciji kao da počinje tek nakon pravog posla. Najprije se proizvod izgradi, a zatim neko napiše šta se dogodilo. Taj model je bio slab i prije razvoja uz pomoć AI-ja. S AI-jem postaje stvarni rizik.

Kad se kod, tekst, interfejsi i tokovi rada mogu generirati vrlo brzo, dokumentacija više nije samo naknadni sloj. Postaje dio mehanizma koji održava proizvod koherentnim.

Zašto je to sada još važnije

AI može generirati implementaciju iz nepotpune namjere. To se često predstavlja kao praktičnost. U praksi to znači da svaka nejasnoća u projektu postaje mjesto na kojem proizvod može odlutati.

Ako je dokumentacija slaba ili zastarjela, različiti ljudi i različiti alati iz istog repozitorija zaključiće da postoje različiti proizvodi.

Jedan saradnik može pratiti trenutno korisničko sučelje. Drugi može pratiti stari README. AI pomoćnik može pratiti najbližu datoteku i izmisliti ostatak.

Problem nije samo ispravnost na nivou koda. Problem je opisuje li projekt još uvijek jedan proizvod umjesto više preklapajućih nagađanja.

Dokumentacija obavlja četiri proizvodna posla

Dobra dokumentacija radi mnogo više od naknadnog objašnjavanja interfejsa.

Prvo, nosi namjeru. Budućim saradnicima govori šta proizvod pokušava postići i u šta se izričito ne pokušava pretvoriti.

Drugo, postavlja očekivanja. Čitaoci mogu razabrati šta postoji sada, šta je planirano i šta se ne bi smjelo opisivati kao već implementirano.

Treće, smanjuje trošak usklađivanja. Novi saradnici, recenzenti, institucije i AI pomoćnici mogu se svi orijentisati bez rekonstruisanja projekta iz fragmenata.

Četvrto, podržava povjerenje. Projekt koji jasno razdvaja trenutno stanje, planirani smjer i eksperimentalni tok rada lakše je procijeniti i lakše održavati.

Let Books je već strukturiran tako

Repozitorij Let Books već pokazuje takav slojevit pristup.

• AGENTS.md definiše svrhu proizvoda, tokove rada, granice domene i dugoročni smjer.
• AGENTS-Implementation.md definiše taktička pravila implementacije i dokumentacije.
• README.md objašnjava trenutno stanje repozitorija i razlikuje sadašnje isporuke od budućih planova.
• docs/ definiše platformu znanja sa pravilima objave, pisanja, lokalizacije i mapiranja izvora.

To znači da dokumentacija ovdje nije samo objašnjenje. Ona je dio načina rada projekta.

Zastarjela dokumentacija je proizvodni dug

Timovi često prepoznaju tehnički dug tek kada se pojavi u kodu. Ali zastarjela dokumentacija stvara sličnu vrstu trenja.

Zastarjela dokumentacija vodi do:

• pogrešnih implementacijskih pretpostavki
• ponavljanja već donesenih odluka
• demoa koji slučajno postaje proizvodna istina
• sporijeg uvođenja novih saradnika
• težeg pregleda jer standard nije jasan

U AI-podržanim tokovima taj se dug nakuplja još brže jer pomoćnici vrlo dobro nastavljaju iz obližnjih, čak i zastarjelih pretpostavki.

Dokumentacija i implementacija moraju činiti lanac

Pravi model nije kruta shema “najprije dokumentacija, zatim kod”. Pravi model je održavani lanac:

• specifikacije definišu namjeru
• dokumenti trenutnog stanja objašnjavaju šta postoji sada
• demo i implementacija čine tok konkretnim
• testovi i validacija provjeravaju očekivanja
• CI održava odstupanje vidljivim

Ako se promijeni jedna karika, treba pregledati i okolne.

Zašto bi to trebalo zanimati širu publiku

Ovo nije samo tehničko pitanje.

Institucije bi to trebalo zanimati zato što dokumentacija utiče na upravljanje, povjerenje pri nabavci, uvođenje novih ljudi, kontinuitet i mogućnost revizije.

Studentima bi to trebalo biti važno zato što je dokumentovanje namjere dio učenja izgradnje pouzdanih sistema, a ne administrativni dodatak.

Širu publiku bi to trebalo zanimati zato što je proizvod sa jasnom dokumentacijom obično i proizvod sa jasnijim odlukama u pozadini.

Praktični test

Korisno pitanje za svaki tim je jednostavno:

Kad bi danas novi saradnik ili AI pomoćnik ušao u repozitorij, da li bi mu dokumenti pomogli da izgradi namjeravani proizvod ili uglavnom nešto što zvuči uvjerljivo?

Ta razlika je razlika između dokumentacije kao komentara i dokumentacije kao dijela proizvoda.

Trajna lekcija

Dokumentacija nije odvojena od kvaliteta proizvoda.

Ona oblikuje implementaciju, pregled, komunikaciju, validaciju i dugoročno povjerenje. U AI-podržanim projektima dokumentacija je dio proizvoda jer je dio sistema koji sprječava proizvodni odmak.

Povezano štivo

• ../../wiki/documentation-traceability.md
• ../../wiki/validation-layers.md
• ai-as-an-oracle.md
• spec-driven-development-in-let-books.md