Сљедивост документације

Зашто је важно

Без следљивости, документацији постаје тешко веровати.

Читаоци не могу рећи:

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

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

Како изгледа следљивост

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

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

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

Једноставан модел ауторитета

Користан модел је:

1. спецификација производа
2. упутство за имплементацију
3. актуелно стање документације
4. демо или имплементацијско понашање
5. тестови и резултати валидације

Ово помаже тимовима да одлуче који артефакт треба да одговори на које питање.

Јавно писање и следљивост

Јавни чланци, есеји и образовни материјал не би требало да се ослањају на било који изворни фајл који се налази у близини.

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

То чини јавно писање с временом одрживијим и мање крхким.

Сљедивост за агенте као и за људе

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

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

Ово је важно јер агенти често поступају по најконкретнијим упутствима која су им при руци. Сљедив Markdown помаже да права инструкција буде јасно видљива.

Let Books контекст

Репозиторијум Let Books већ подржава следљивост кроз:

• AGENTS.md
• AGENTS-Implementation.md
• README.md
• docs/README.md
• docs/blog/README.md
• docs/sources/README.md
• изворне мапе према docs/sources/

Такође садржи Markdown водиче који функционишу као оперативни контекст који се може пратити за рад агента, као што су:

• docs/android-debugging.md за избор тока посла за мобилно отклањање грешака и коришћење алата
• docs/style-guide/publishing/ubuntu-tooling.md за очекиване могућности алата и верификације

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