Про документацию в эпоху 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
Подписаться
Пару недель назад делал доклад про документацию в эпоху 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
Подписаться