Документација је део производа

Многи тимови и даље говоре о документацији као да почиње тек после правог посла. Најпре се производ изгради, а затим неко напише шта се догодило. Тај модел је био слаб и пре развоја уз помоћ AI-ја. Са AI-јем постаје стварни ризик.

Када се код, текст, интерфејси и токови рада могу генерисати веома брзо, документација више није само накнадни слој. Постаје део механизма који одржава производ кохерентним.

Зашто је то сада још важније

AI може да генерише имплементацију из непотпуне намере. То се често представља као практичност. У пракси то значи да свака нејасноћа у пројекту постаје место на којем производ може да одлута.

Ако је документација слаба или застарела, различити људи и различити алати из истог репозиторијума закључиће да постоје различити производи.

Један сарадник може пратити тренутно корисничко сучеље. Други може пратити стари README. AI помоћник може пратити најближу датотеку и измислити остало.

Проблем није само исправност на нивоу кода. Проблем је да ли пројекат и даље описује један производ уместо више преклапајућих претпоставки.

Документација обавља четири производна посла

Добра документација ради много више од накнадног објашњавања интерфејса.

Прво, носи намеру. Будућим сарадницима говори шта производ покушава да постигне и у шта се изричито не покушава претворити.

Друго, поставља очекивања. Читаоци могу да разазнају шта постоји сада, шта је планирано и шта не би смело да се описује као већ имплементирано.

Треће, смањује трошак усклађивања. Нови сарадници, рецензенти, институције и AI помоћници могу сви да се оријентишу без реконструисања пројекта из фрагмената.

Четврто, подржава поверење. Пројекат који јасно раздваја тренутно стање, планирани смер и експериментални ток рада лакше је проценити и лакше одржавати.

Let Books је већ структуриран тако

Репозиторијум Let Books већ показује такав слојевит приступ.

• AGENTS.md дефинише сврху производа, токове рада, границе домена и дугорочни смер.
• AGENTS-Implementation.md дефинише тактичка правила имплементације и документације.
• README.md објашњава тренутно стање репозиторијума и разликује садашње испоруке од будућих планова.
• docs/ дефинише платформу знања са правилима објаве, писања, локализације и мапирања извора.

То значи да документација овде није само објашњење. Она је део начина рада пројекта.

Застарела документација је производни дуг

Тимови често препознају технички дуг тек када се појави у коду. Али застарела документација ствара сличну врсту трења.

Застарела документација води до:

• погрешних имплементационих претпоставки
• понављања већ донетих одлука
• дема који случајно постаје производна истина
• споријег увођења нових сарадника
• тежег прегледа јер стандард није јасан

У AI-подржаним токовима тај се дуг гомила још брже јер помоћници веома добро настављају из оближњих, чак и застарелих претпоставки.

Документација и имплементација морају чинити ланац

Прави модел није крута шема „најпре документација, затим код“. Прави модел је одржавани ланац:

• спецификације дефинишу намеру
• документи тренутног стања објашњавају шта постоји сада
• демо и имплементација чине ток конкретним
• тестови и валидација проверавају очекивања
• CI одржава одступање видљивим

Ако се промени једна карика, треба прегледати и околне.

Зашто би ово требало да занима ширу публику

Ово није само техничко питање.

Институције би ово требало да занима зато што документација утиче на управљање, поверење при набавци, увођење нових људи, континуитет и могућност ревизије.

Студентима би ово требало да буде важно зато што је документовање намере део учења изградње поузданих система, а не административни додатак.

Ширу публику би ово требало да занима зато што је производ са јасном документацијом обично и производ са јаснијим одлукама у позадини.

Практични тест

Корисно питање за сваки тим је једноставно:

Кад би данас нови сарадник или AI помоћник ушао у репозиторијум, да ли би му документи помогли да изгради намеравани производ или углавном нешто што звучи уверљиво?

Та разлика је разлика између документације као коментара и документације као дела производа.

Трајна лекција

Документација није одвојена од квалитета производа.

Она обликује имплементацију, преглед, комуникацију, валидацију и дугорочно поверење. У AI-подржаним пројектима документација је део производа јер је део система који спречава производни одмак.

Повезано штиво

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