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

Зошто е важно

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

Читателите не можат да кажат:

• дали изјавата е актуелна
• дали некое однесување е намерно
• дали барањето доаѓа од спецификација на производот или несреќа при имплементација
• дали јавен напис ја одразува одобрената насока на производот

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

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

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

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

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

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

Корисен модел е:

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 за очекуваните можности за алатки и верификација

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