Markdown во развој на производ

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

Markdown често се третира како погодност за пишување. Во работата водена од спецификации, тоа е покорисно од тоа.

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

Тоа е важно за:

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

Во што е добар §Markdown

Markdown работи добро кога содржината треба да биде:

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

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

Она што Markdown не го прави само по себе

Markdown е корисен, но не ја наметнува исправноста сама по себе.

Тоа само по себе не може да гарантира:

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

Затоа Markdown треба да биде дел од поширок систем, а не да се меша со целиот систем.

Markdown во работен тек заснован на спецификации

Во работниот тек управуван од спецификации, Markdown е највредно кога се наоѓа во синџир на авторитет.

На пример:

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

Markdown е медиум кој им помага на тие слоеви да останат видливи и прегледливи.

Зошто ова е важно во работата со помош на вештачка интелигенција

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

Markdown помага бидејќи е:

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

Тоа го прави силен формат за меморија на производот.

Но, вештачката интелигенција исто така прави едно ограничување поочигледно: ако Markdown е нејасен, застарен или контрадикторен, асистентот може да генерира брзо оддалечување од него. Значи, вредноста не доаѓа само од форматот, туку и од одржувањето на содржината.

Markdown како насоки за агентот

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

Ова е особено корисно кога документот прави повеќе од објаснување на тема и наместо тоа доловува:

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

Во тие случаи, Markdown станува повеќе од објаснување. Станува траен интерфејс помеѓу знаењето на складиштето и однесувањето на агентот.

Let Books примери за насоки за агенти

Работен тек за отстранување грешки на Android

docs/android-debugging.md е силен пример.

Може да се чита како водич за луѓе, но исто така му дава на агентот конкретна оперативна насока како што се:

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

Тој вид Markdown не опишува само домен. Активно го води работниот тек и изборот на алатки.

Алатка и подготовка на околината

docs/style-guide/publishing/ubuntu-tooling.md е уште еден добар пример.

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

• Playwright за проверка на интерфејсот и слики од екранот
• Hunspell за проверка на правопис
• ImageMagick и OCR алатки за визуелни и лажни работни текови
• Алатка поврзана со ADB за отстранување грешки на Android

Овој вид Markdown му помага на агентот да расудува за очекуваниот синџир на алатки наместо да погодува од генеричките стандардни поставки.

Практична импликација

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

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

Најдобрите документи ги прават и двете.

Тие остануваат читливи упатства или водичи за луѓето, а истовремено се доволно специфични за да го насочат однесувањето на агентот на повторливи начини.

Let Books контекст

Репозиториумот Let Books веќе користи Markdown за неколку слоеви на меморија на производи, вклучувајќи:

• AGENTS.md
• AGENTS-Implementation.md
• README.md
• README и водичи од областа на документи
• изворни карти под docs/sources/

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

Практично правило

Корисното правило е едноставно:

Користете Markdown за да ги направите намерите на производот видливи, прегледливи и способни за поврзување. Не претпоставувајте дека само Markdown ја одржува таа намера вистинита.

Вистината сепак зависи од:

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