Про документацию в эпоху AI

Пару недель назад делал доклад про документацию в эпоху AI. Записи у меня к сожалению нет, но поделюсь основными тезисами:

1⃣ AI сильно упростил не только написание кода, но и генерацию документации. Нужна ли она, если теперь есть возможно получить ответы на естественном языке прямо по коду? Я считаю, что да.

2⃣ Надо разделять документацию по критерию - является ли она источником истины (например, функциональные или архитектурные требования) от документации сгенерированный по коду (quick start, user guide и тд). Это важно, чтобы понимать где искать ответ - как система должна работать (в исходных требованиях) и как система на самом деле работает (в коде).

3⃣ У разных команд (фриланс, стартап, корпорация) разные требования к объему и пайплайну работы с документацией. Не переусложняйте, но и не забивайте совсем.

4⃣ Люди по-прежнему несут ответственность за документацию

5⃣ Назначьте и контролируйте ownership для документов.

6⃣ Начните хранить документацию вместе с кодом (markdown)

7⃣ Ревьювьте изменения в доках вместе с PR (удобно если лежит вместе с кодом)

8⃣ Используйте MCP / CLI для чтения и обновления документации, которая хранится отдельно от кода

9⃣ Встройте генерацию документов и автоматическое обновление в ваш пайплайн (skills, agents.md или отдельный hook в CI/CD)

1⃣0️⃣ Приведите документацию в порядок. Для AI агентов работает правило: garbage in - garbage out

Подписаться