Протягом останніх 15 років я працював над десятками програмних проектів, і майже кожен раз документація була жахливою. Розробники недооцінюють необхідність документації, тому що думають, що вони вже все розуміють. Менеджери недооцінюють це, оскільки припускають, що розробники можуть просто прочитати код і зрозуміти проект за пару годин. Навіть коли люди не недооцінюють документацію, їм часто не вистачає часу і можливостей для неї.Точний, оновлений огляд зазвичай сидить в головах старших розробників, які вже несуть багато відповідальності. Не існує спільної культури або інтуїції щодо того, що повинно бути задокументовано і що очевидно. Розробники часто додають коментарі до тривіальних функцій або описують параметри, коли більш чіткі перемінні імена або типи вирішили б проблему. Можливо, документація просто застаріла? Тільки , вказуючи на те, що багато команд розглядають документацію як «факультативну формальність» 4% компаній завжди документують свої процеси https://www.bptrends.com/bpt/wp-content/uploads/2015-BPT-Survey-Report.pdf/ У той же час ми маємо сильні докази того, що без гарної документації бізнес просто втрачає величезну кількість часу-грошей: «Недостатня документація» названа 41% розробників як головна причина втраченого часу, з 69% розробників втрачають 8+ годин на тиждень на такі неефективності (що дорівнює ~ $ 18,5 млн в річній втраченій продуктивності на 1000 розробників) https://newsletter.getdx.com/p/state-of-developer-experience-2024 Налаштування нового інженера займає 3–9 місяців, сильно залежить від документації https://stripe.com/files/reports/the-developer-coefficient.pdf Відсутність документації є основним компонентом технічного боргу (https://www.informit.com/store/economics-of-software-quality-9780132582209) Експеримент з більш ніж 30 програмістами показав, що відсутність документації викликає приблизно 21% більше часу, витраченого на розуміння коду під час завдань з обслуговування https://hci.com.au/get-documentation-budget Отже, які фактичні перешкоди стоять за такою поширеною нестачею документації? У блискучій роботі Ендрю Форварда «Документація програмного забезпечення — Будівництво та підтримка артефактів комунікації» зроблено гарне дослідження фактичних причин. External Factors Influencing Documentation Quality Як бачите, відсутність часу і бюджету пов'язана з розчаруванням, що документаційні зусилля можуть стати марними і швидко застаріти. Отже, якщо ми зменшимо ручні зусилля і вирішимо проблему того, що документація стає застарілою, ми можемо зробити значний крок вперед. Спільнота розробників вже запровадила підходи, такі як Javadoc та подібні інструменти, які автоматично генерують документацію з підписів коду. Отже, нам все ще потрібна добре написана, актуальна, читається людиною документація. Справжній виклик полягає в тому, що документація не є одноразовою, а Навіть якщо команда пише хороші документи спочатку, код розвивається швидше, ніж звички документації.Без безперервної синхронізації документація стає обманливою — що ще гірше, ніж відсутність. Живий артефакт Це означає, що бульбашка не документації, але . Писати Тримати його правильним Рішення Хто AI насправді добре поєднує прості шаблони між кодом і документами.Є кілька гарних рішень, де ви можете автоматизувати дрейф документації за допомогою AI: Merge request rules, pointing agent to existing documentation and changed code base Claude Code documentation agent that keeps project docs up to date with Docusaurus. npx claude-code-templates@latest --agent=documentation/docusaurus-expert --yes Цей підхід добре працює для: Оновлення описів високого рівня Резюме коду наміру Відновлення застарілої фрази Відновлення відсутнього контексту Однак у нього є чіткі обмеження: Він бореться з виявленням структурних невідповідностей (наприклад, недокументованих env vars, портів, прапорів CLI, прапорів особливості). Це може галюцинувати, особливо коли документи є неповними або неоднозначними. Він не виробляє відстежуваних, детерміністичних перевірок - кожен біг може генерувати трохи інший результат. Вона не може достовірно сказати, що важливо і що таке шум без знань домену. Іншими словами, AI може допомогти Але поки що він не вважається надійним. . rewrite and improve text source of truth validator Статичні перевірки Інструменти як вирішує цю проблему, розглядаючи документацію як те, що необхідно постійно контролювати, як якість коду або дрейф інфраструктури. Вона працює чисто алгоритмічно, тому не зачіпається галюцинаціями, хоча, звичайно, все ще можливі фальшиві позитивні. Дуку Ducku працює шляхом вилучення структурних сигналів з вашого сховища — змінних середовища, маршрутів API, пунктів введення послуг, імпорту модулів, структури каталогів, ключів конфігурації — і порівняння їх з тим, що посилається на ваші READMEs і wiki. Теперішні можливості Перевірка наявності суб'єктів: виявляє, коли змінні середовища, ключі конфігурації, порти, маршрути API або назви сценаріїв з'являються в документації, але не в коді (і навпаки). Паралельне покриття суб'єктів: визначає групи подібних елементів (послуги, робочі місця ETL, обробники lambda, команди CLI) і знаменує недокументовані додатки. Аналіз мертвих модулів: виявляє файли, які не імпортуються / використовуються в будь-якому місці - або вхідні точки, які заслуговують пояснення, або застарілі артефакти. Перевірка цілісності URL: виявляє зламані або застарілі посилання на внутрішні або зовнішні ресурси. Заклинання і послідовність стилю: основна гігієна, яка зазвичай ігнорується. Це вже достатньо, щоб зменшити велику частину тихої документації, що дрейфує в реальних проектах. Висновок Документація не провалиться, тому що інженери безтурботні. що тримає його узгодженим з системою, яку він описує. Код має тести. Інфраструктура має виявлення дрейфу. CI має ворота політики. Документація, в більшості команд, не має нічого. no feedback loop AI може поліпшити фрази і відновити контекст, але не може достовірно сказати, чи є документація Статичні перевірки, з іншого боку, можуть підтвердити фактичне вирівнювання, але вони не можуть пояснити намір або логіку домену. correct Разом вони можуть принести те, що вам потрібно.
