Правила разработки документации ML-проекта

Полезная, актуальная и при этом полная документация - миф или реальность? В первой части статьи обсудим зачем вообще нужна документация (а когда она и не нужна вовсе), поговорим о распространённых проблемах и ошибках, а во второй - посмотрим на примеры специфичной документации, связанной с ML-моделями и данными. Статья представляет собой текстовую версию доклада Lean DS.

При обсуждении какого-то явления, полезно сначала посмотреть на его определение. Тут нам поможет старая добрая Википедия:

“Письменный текст или иллюстрация, которая сопровождает программное обеспечение или интегрирована прямо в исходный код. Документация объясняет, как работает ПО или как его использовать. Может иметь разное значение для людей с разными ролями в команде”

Определение действительно неплохое, в нём содержится несколько важных свойств документации:

может существовать отдельно или “зашита” в код (documentation-as-code)

может иметь разные формы - текст, картинка, видео

один и тот же документ может по-разному использоваться разными людьми

Кому нужна документация? Давайте посмотрим на документацию с точки зрения ML-команды. Кто ей может пользоваться?

Сама команда DS-разработчиков

Тимлид этой команды

Внешние пользователи (менеджмент компании, заказчики, конечные пользователи DS-продукта)

Мы разрабатываем ИИ-решение для радиологов и вопрос документации для нас всегда был очень острым. Без качественной документации невозможно “выкатывать” новые релизы и четко планировать развитие продукта, очень сложно “онбордить” новых сотрудников, да и вообще плохое качество документации чревато разными проблемами, особенно это начинает чувствоваться при масштабировании продуктов и команды.

Самим ML-командам документация служит для:

Снижения сложности вникания в новые проекты.

Возможности получения актуального референса (например, при актуализации старой гипотезы, отложенной в “долгий ящик”)

Создания культуры открытости и обмена знаний внутри команды

Повышения количества новых идей и структуризации знаний о проектах

Лидам документация помогает всегда оставаться в курсе актуального состояния проекта, позволяет быстро делиться информацией со стейкхолдерами проекта, формировать и обновлять вектор развития, а также облегчать процесс онбординга новых сотрудников.

Документация помогает и внешним пользователям (здесь под внешними пользователями я понимаю и другие команды на проекте): с ее помощью они могут всегда получить актуальную информацию по продукту и не дергать лишний раз членов команды. Например, прочитать readme и самостоятельно подключиться к API. Также документация ускоряет процесс принятия управленческих решений, делая их более точными и основанными на актуальной информации.

Прежде чем создавать любой документ или внедрять какую-то практику, связанную с документацией, рекомендую обязательно пройтись по такому чек-листу:

Сколько будет стоить (в деньгах, времени, раздражении) написание и поддержка документа или практики?

Кто будет читать документ, как часто и в каких ситуациях?

Кто, как и когда будет актуализировать документ? Будут ли члены команды это делать добровольно?

Можно ли полностью или частично автоматизировать процесс актуализации документа? Частые проблемы, связанные с документацией В документации содержится слишком мало информации. Приходится часто дергать членов команды для получения нужных данных

Информации слишком много, и она разбросана по разным источникам - wiki, Slack, гугл-документы и презентации, бумажные носители

Информация неактуальна

Информация дублируется в разных источниках

Итак, мы разобрались с основными целями создания и ведения документации и знаем, с какими проблемами нам предстоит столкнуться. Теперь поговорим о “правилах хорошего тона”, использование которых сильно уменьшит вероятность появления этих самых проблем.

Правила структуры и оформления:

Единая точка входа ко всей документации проекта. Это может быть страница в Notion, фрейм в Miro или Markdown-документ, форма не так важна. Главное, чтобы с этой страницы любой человек мог получить доступ к нужной ему информации.

Единые правила оформления и стиля, наличие шаблонов. Немаловажным фактором для восприятия пользователем документации является наличие и консистентность общего стиля оформления документации.

Стиль описания и подачи информации в документации соответствует культуре команды. Нет смысла придерживаться ненужного формализма во внутренних документах команды.

В документах есть ссылки на другие релевантные документы.

Важные места выделены

Используются оптимальные методы передачи информации. В зависимости от задачи документа может использоваться не только текст, но и картинки, графики, диаграммы, видео

Правила использования и актуализации:

Определена целевая аудитория каждого документа - кто, как и зачем будет его использовать

Если документация не используется самой командой, то её актуализацию стоит встраивать в процессы в формате “definition of done”. Например, нельзя зарелизить новую модель, не обновив документацию

Использование методологии (“docs as code”) там, где это актуально. В данном случае документация является частью кодовой базы, лежит в репозитории и пишется в IDE. Данный подход “из коробки” даёт возможность версионирования, тестирования, ревью изменений документации.

Производится регулярная ревизия документации. Включает себя в том числе отказ от устаревших или лишних документов.

Встречи команды должны порождать новые “артефакты” (документы по итогам встречи). Например, дорожная карта реализации или лист договоренностей.

Инвентаризация технического долга по документации. Да-да, техдолг по документации тоже является техдолгом.

Можно ли как-то измерить качество документации? Если у нас уже есть какая-то документация и процедуры её актуализации, можно ли попробовать померить её качество? Такие показатели действительно есть:

Покрытие - какая часть кода проекта или DS-пайплайна покрыта документацией

Доступность - сколько времени или кликов в среднем занимает поиск нужного документа

Читаемость - насколько легко читать этот документ

Количество посещений/обновлений документа за период

Мы пока не дошли до того, чтобы регулярно замерять динамику этих показателей, пока это кажется лишним. Но в качестве точки среза - почему нет?

Документация ML-проекта В первой части статьи я рассказал про документацию процесса разработки. Однако ML-разработка довольно сильно отличается от классической разработки. Есть ли различия в документации?

Если максимально упростить пайплайн ML-разработки, то он будет выглядеть следующим образом:

Оценивается осуществимость и значимость проекта

Производится сбор, очистка и разметка данных

Генерируем гипотезы, тренируем модели

Оцениваем качество и устойчивость лучшей модели

Деплоим модель

Осуществляем мониторинг

Понятно, что этот пайплайн весьма условен, каких-то этапов может не быть, какие-то могут добавиться. Да и носит он, конечно, циклический характер, например на этапе оценки качества мы можем вернуться на этап генерации новых гипотез и построения моделей. Тем не менее, такое разделение позволит нам посмотреть на разные виды документации, характерные для разных этапов.

Что же может быть входной точкой в документацию?

В нашем случае это карточка проекта, оформленная в Notion.