Igas dokumentatsioonis, millega olen töötanud, oli üks kummaline leht. Nelja platvormi seadistusjuhendid käivad samas järjekorras: mida on vaja, paigaldamine, sisselogimine, kontroll, et kõik töötab, ja mida teha, kui ei tööta. Siis tuleb aasta hiljem viies platvorm, keegi kirjutab juhendi kiirustades ning see algab veaotsingust ja kontrolli osa pole üldse. Lugejad märkavad seda. Nad tulid teiselt lehelt, teavad, kust otsida, ja seda, mida nad otsivad, seal ei ole.
Lehtede ühtsena hoidmine on suur osa sellest tööst ja just selles on tehisaru mustand kõige nõrgem, kui küsid tavalisel viisil. „Kirjuta Linuxi seadistusjuhend“ annab sulle mõistliku seadistusjuhendi. Lihtsalt mitte sinu oma. Pealkirjad on teised, sammud on teisiti nummerdatud ja hoiatus on vales kohas.
Näita lehte, mis juba töötab
Lahendus, mida nüüd kasutan, on igav. Ma ei kirjelda vormi, vaid näitan seda. „Kirjuta Linuxi juhend samas vormis nagu Windowsi juhend“ töötab paremini kui ükski mall, mida olen proovinud sõnadega selgitada, sest agent loeb päris lehte: selle pealkirju, iga osa pikkust, piltide kohti ja seda, kuidas viimane osa juhatab lugeja järgmisele lehele.
Ritemarkis on dokumentatsioon kaustas minu arvutis ja agent töötab selles kaustas. Ta saab avada Windowsi juhendi, kausta juures oleva stiilifaili ja selle versiooni väljalaskemärkmed, millest ta kirjutab. Ma ei kleebi midagi vestlusaknasse ja agent ei pea arvama, millised teised lehed välja näevad.
Loe plaan enne kirjutamist läbi
Teine pool on sama tähtis. Enne kui agent uue lehe kirjutab, palun tal kõigepealt plaan teha. Ta loeb allikad läbi ja ütleb, mida ta teeb ja mille kust võttis, ning kaustas ei muutu midagi enne, kui ma plaani kinnitan.
Ülal olev kuvatõmmis on koolitusprojektist, mitte dokumentatsioonist, kuid see näitab seda hetke hästi. Claude'il paluti lähteülesande põhjal Module 5 planeerida ja plaanis on kirjas, et ta teeb faili Modules/Module 5.md „samas vormis nagu Module 4“, ning loetletud on osad, mille ta üle võtab. Selle all on loetelu sellest, mida allikad talle annavad. Viimane rida ütleb, et ühtegi faili pole veel muudetud. Nuppe on kaks: Approve & continue ja Keep planning.
Dokumentatsioonilehe puhul leian just plaanist enamiku vigu. Kui teine osa on plaanis „Veaotsing“, tean, et agent luges vale juhendit. Kui plaan ütleb, et Linuxi versioonil on sisselogimise samm, mida väljalaskemärkmetes pole, küsin, kust see tuli. Kümnerealise plaani parandamine võtab minuti. Valmis lehe parandamine, mis on vormist kõrvale kaldunud, võtab terve õhtu, sest kõrvalekalded on laiali igas osas.
Mida see ei lahenda
Vorm on ühtsuse lihtsam pool. Pealkirju ja järjekorda kopeerib agent hästi. Väikeste harjumustega osade sees läheb tal kehvemini: kas kirjutad „vali“ või „klõpsa“, kas iga samm lõpeb sellega, mida lugeja peaks nägema. Kausta juures olev stiilifail katab sellest osa ja ma loen tulemust ikka nii, nagu loeksin kolleegi esimest mustandit.
Agent kopeerib ka vead truult. Kui Windowsi juhendis on nõrk osa, on Linuxi juhendis sama nõrk osa. Mõnikord on see hea hetk parandada kõigepealt näidisleht ja siis uuesti küsida.
Tagasi saan aja, mis kulus varem viienda lehe sarnaseks tegemisele lehtedega ühest neljani. Selle asemel kontrollin, kas sammud on õiged, ja seda ei saa minu eest kontrollida ükski plaan.
Kui kirjutad dokumentatsiooni, näitab tehniliste kirjutajate leht väljalaskemärkmete, API-dokumentatsiooni ja teadmusbaasi tööd Ritemarkis ning Stiilijuhend, mida sinu tehisaru kunagi ei lugenud selgitab faili, mis on kausta juures.