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

Многу тимови сè уште зборуваат за документацијата како да почнува дури по вистинската работа. Прво се гради производот, а потоа некој запишува што се случило. Тој модел беше слаб и пред развојот со помош на 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