Хабр Курсы для менеджеров
РЕКЛАМА
Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!
Поток Менеджмент доступен 24/7 благодаря поддержке друзей Хабра
Комментарии 19
В результате документация превращается в вторичный артефакт, за который никто не несёт реальной ответственности.
Это, кстати, еще не самый плохой вариант. Гораздо хуже, когда все описанные негативные эффекты присутствуют (нет нормального версионирования и ревтю и т.д.), и за такую документацию приходится нести ответственность.
Агенты сейчас сами обновляют релевантные доки после комитов. Мне кажется уже не нужно будет заморачиваться инструментами и ручной работой. Так, проверять иногда.
Докам даже не надо быть в репозитори.
Проверять всегда, если проект хоть мало-мальски нетривиален. Агенты упускают важные детали, галлюционируют. Как раз с ними лучше работать в репозиториях, чтобы видеть, что там наворочено в доках.
ну про репозиторий не спорю, считаю намного удобнее так. Но люди не меняются от местонахождения документации 🙂.
Во многих проектах про доки в репозитории так же забывали как про доки в конфлюенс.
Есть несколько полу решений (DoD, custom linter hook), но они не стабильные.
А вот LLM комфортно справляется с обновлением доков сразу (пока не супер идеально, но вероятно через пару лет, намного лучше людей).
Конечно есть доки не для БЯМ, например внешняя информация (типа "берем Х потому что нам так дешевле"), т.е. люди еще нужны иногда не только для ревью. Но в общей сумме тенденция имхо ясна.
Я бы добавил в статью явный пример связки генератора wiki + разметки. Упоминается mkdocs, с ним вроде markdown.
Antora + asciidoc - ни слова.
Также в статье прям по самым верхам, как и десятках других статей, которые я читал при изучении подхода.
Автоматизация доки сильно упростить жизнь тем же аналитикам, но не полностью от необходимости ее вести.
Какой сам процесс доставки документации? Как оно пересекается с разработкой? Как с этим работают другие участники команды? Примеры из личной практики?
А то получается вся статья о том, что "дышать через нос - очень удобно"
Мы используем прямо такой же подход, ascidoc, ревью, гит и публикация на анторе,
я тоже практикую doc as code.
Потому что постоянная путаница с версиями файлов. нужные еще и херились со временем.
Документацию пишет аналитик. Ну, хотя бы фт. Разработчики ругаются от необходимости ее писать.
У нас аналитик отвечает за доку. И кросс ревью только аналитики делают.
Сборку документацию не встроили в пайплайн, но есть ручная джоба по сборке документации из конкретной ветки. Запускаем для релизов
Мы диплодок заюзали для автоматической раскатки документации из пайплайна
при подходе api-first СА пишет много артефактов. Как минимум для удобства проектирования API и снижению путаницы делали такой мини-процесс
в корне лежат api-спеки всех сервисов в актуальном виде -> аналитик использует их и в JSON (через плагин в IDE) просто явно правит доку, оный же swagger, без веб инструмента -> отдает в разработку -> проходит этап реализации и далее при заливке в ветку сервиса срабатывает триггер и вебхуком дергаем актуальную версию спеки сервиса и кладем ее в корень
Таким образом аналитик всегда имеет актуальную версию спеки, для доработки
+ я еще дописывал скрипт для второго пайплайна, который генерит wiki страницы для каждого метода в отдельный раздел
Есть правда пару важных условий:
при проектировании описывать обязательно все теги description, operationId, example
обязательно отмечать это в entity (на этапе разработки)
Но, как мне кажется, это очень маленькая цена за то, что не придется тратить сотни человекочасов, что скриптами можно прогнать за секунды
А спросить копилота как работает код?
Этот конечно может и хорошо. Да наверное и правильно. В какой-то степени. Вот только придется давать не программистам допуск к коду. И ревьюить их изменения. А оно программистам надо?
Если же вы думаете, что программисты сами будут писать документацию, я вас умоляю...
Docs as Cod - а Роза упала
Я работал с ascidoc’ом в роли системного аналитика/лида интеграции в большом финтехе. Очень много неудобного по сравнению с ревью в том же word’е в режиме правки.
1) Как построена работа с другими отделами? Как пересылаются документы PM’ам, БА, подрядчикам? Все они (особенно бизнес) умеют работать с git’ом?
2) Через какие надстройки визуализация?
3) Как проводиться ревью документа? Как визуализируются правки по сравнению с прошлой версией дока? Возможно ли оставлять комментарии привязанные к выделенным кускам текста? Аналог «исправлений в режиме правки в ворде»?
PS Да и писать такие доки в среде разработки(sic!) в два окна, одно из которых код, втрое «визуализатор» то еще удовольствие
Имхо. Непонятно про какую документацию речь. Например QA-шные тесткейсы из зефира хранить рядом с кодом? А подробное текстовое (человекопонятное) описание пользовательских сценариев? Много воды -- всю статью можно сократить до одного предложения "Старайтесь использовать для документации такой формат файлов который можно положить в репозиторий". У нас, например, используются подробные ридми в md-формате с описанием внешних интеграций, правил работы с кодом, инструкции как локально развернуть и т.п. в репозиториях проектов. Но пользовательская, менеждерская и QA-шная доки живут отдельно в удобных для исполнителей форматах
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Docs as Code: документация, которая живёт вместе с кодом