Dokumentáció, amit használnak

Kinek írjuk

A dokumentáció akkor lesz halott, ha senki nem tudja, kinek szól. A gyakorlatban három különböző olvasó van, és mindhárom más kérdéssel érkezik.

Az üzemeltető azt kérdezi, mit csináljak, ha elromlott. A fejlesztő azt, hogyan tudom módosítani anélkül, hogy elrontanám. A döntéshozó azt, mit csinál ez és mennyibe kerül. Egyetlen dokumentum, ami mindhármat próbálja kiszolgálni, egyiket sem fogja.

A döntési napló

A legértékesebb dokumentáció nem azt írja le, hogy mi van, hanem hogy miért az van. Ezt a formát döntési naplónak hívjuk, és egy bejegyzés négy sorból áll.

Mi volt a kérdés. Milyen lehetőségek merültek fel. Mit választottunk. Miért, és mit adtunk fel érte.

Ez a négy sor menti meg a következő embert attól, hogy fél év múlva ránézzen a rendszerre, értetlenkedjen, és átírja azt, amit valaki nagyon jó okból csinált úgy. Az újraírt megoldás pedig ugyanabba a falba fog futni, amit már egyszer megkerültünk.

Mit tegyünk a promptokkal

Az AI rendszereknél van egy sajátos dokumentációs kérdés. A rendszerprompt maga is dokumentum, csak épp fut is. Ha ez sok helyen, sok változatban van szétszórva, akkor a rendszer viselkedése kideríthetetlenné válik.

Érdemes egy helyen tartani, verziózni, és mellé írni, hogy melyik szabály miért került bele. A legtöbb rendszerpromptban van néhány mondat, amit valaki egy konkrét hiba után tett bele, és ha ez nincs leírva, akkor a következő ember ki fogja törölni, mert feleslegesnek látszik.

A mennyiség kérdése

A jó mérték az, ami mellett egy új ember egy nap alatt működésbe tud lépni. Ha ennél kevesebb van, akkor kérdezni fog, és a válaszok emberfüggővé válnak. Ha ennél sokkal több, akkor nem fogja elolvasni, és ugyanoda jutunk.

A dokumentációt ugyanúgy karban kell tartani, mint a kódot. Ha nincs erre kijelölt gazda, akkor néhány hónap múlva félrevezető lesz, ami rosszabb, mintha nem lenne.