Контекст проекта
Я участвовала в редизайне интерфейса платформы для построения и управления потоками данных. Пользователи платформы — инженеры, создающие и настраивающие последовательности обработки данных из различных источников.
Моя роль
Я присоединилась к команде на этапе перехода продукта с версии 2 на версию 3.
Моя задача как дизайнера интерфейсов — обновить UI и UX визуального конструктора потоков, не только сохранив привычные сценарии, но и интегрировав новые.
Задача
Команда планировала внедрить в продукт функцию встроенного документирования — возможность добавлять заметки и аннотации к элементам рабочей схемы, а затем выгружать их в виде структурированной документации.
У команды уже был примерный каркас, от которого они отталкивались в выборе функционала для этой фичи: MediationZone. У этих ребят была генерация и выгрузка документации, и мы хотели повторить их же трюк полностью с небольшим добавлением (вместо одной заметки на все дать возможность делать и одну заметку на все, и заметки на отдельных агентов).
Я предположила, что не все так просто, а стоит узнать, что об этом думают те, кто непосредственно пользуется продуктом и пишет документацию, а также подсмотреть решения аналогичных продуктов.
Анализ конкурентов
Изучила подходы к встроенной документации в Zapier, n8n и Make. MediationZone в этом списке находится лишь потому, что именно он являлся источником вдохновения для этой задачи.
🐰 Везде есть возможность оставлять заметки, но реализация разрозненная.
🐸 Только часть сервисов поддерживает базовое форматирование (начертание шрифта, списки, вставка ссылки или медиа).
🐮 Полноценной генерации документации «одним пакетом» — нет ни у кого (кроме MZ).
Вывод: индустрия не имеет единого стандарта встроенной документации, а значит — продукт может предложить собственное, более цельное решение.
Интервью
Я провела серию интервью с инженерами и интеграторами, которые создают и поддерживают рабочие потоки. Полученные данные систематизировала методом Affinity Diagramming.
Ключевые инсайты:
🛞 Встроенная документация действительно востребована: пользователи хотят фиксировать логику прямо в рабочем пространстве, не переходя в сторонние инструменты.
🛞 Большие документы с описаниями теряют ценность: их не читают, сложно поддерживать форматирование и обновлять скриншоты.
🛞 Для разных команд заказчика нужны разные уровни детализации в документации.
🛞 Основные боли связаны с:
– Разрозненностью источников (файлы, Confluence, Wiki)
– Отсутствием единой структуры документации
– Невозможностью быстро найти нужное место или агент.
Желаемые возможности:
🐉 Добавлять заметки к агентам, связям и общему проекту;
🐉 Автоматически экспортировать всю документацию (с изображением схемы, описаниями и зависимостями);
🐉 Выбирать глубину и формат экспорта (файл / Confluence / Wiki);
🐉 Поддерживать простое форматирование текста;
🐉 Просматривать и перемещаться по всем заметкам внутри проекта.
Направления решения
📝Контекстные заметки в рабочем пространстве
Добавить возможность описывать решение на нескольких уровнях глубины:
— Комментарии в коде (в продукте предусмотрены два режима просмотра: source / design)
— Описания шагов (агентов)
— Описание рабочего потока (и других дизайн-компонент)
— Описание проекта (общее описание, зачем все дизайн-компоненты собрались вместе)
🍿+🥤Одновременное отображение заметок и описываемого элемента на одном экране
Отображать заметку рядом с описываемым элементом, а не перекрывать его. Требует прототипирования, юзабилити тестирования.
🪸Настраиваемая глубина экспорта описания, или Возможность выбрать назначение документации
При сборе и экспорте документации предусмотреть возможность включать или выключать отдельные части документации, например, выгружать вместе с описанием вложенных зависимостей или просто перечислить их списком. Также можно сделать пресеты «Для разработчиков», «Для 1-й линии поддержки» с настроенной детализацией выходной документации.
🎛️Возможность добавлять текущие настройки в заметки
Добавить возможность упоминать текущие настройки агентов или настройки всего потока в заметки, при этом сохранять связь или оставить актуальные на момент добавления значения. Это поможет в документации акцентировать внимание на ключевых параметрах для запуска того или иного элемента.
🤡Изучить тонкости импорта документов в Confluence, Yandex Wiki
Хотя прямой экспорт в Confluence или аналоги невозможен, стоит минимизировать ошибки при импорте документа в эти сервисы.
