Этим летом команда из трех разработчиков в Coveo оценила четыре платформы для документации, выбрала одну из них и конвертировала в нее более 5000 статей. У них была помощь: ИИ-агенты для кодинга создали прототипы, помогли написать конвейер конвертации и, что наиболее важно, устранили проблемы, выявленные нашими отчетами о качестве, выполняя итерации локальных сборки до тех пор, пока не смогли открыть пул-реквесты. Без этих агентов проект такого масштаба занял бы у столь небольшой команды гораздо больше времени.
Результатом станет новый сайт документации, созданный на Rspress, генераторе статических сайтов на базе сборщика Rspack, написанного на Rust. Он заменяет сайт Jekyll, который годами служил основой для нашей документации. Он станет доступен по адресу beta.docs.coveo.com через несколько дней, а через несколько недель после этого превратится в docs.coveo.com.
Вот почему мы это сделали, как ИИ изменил подход к выбору платформы и переносу контента, в чем мы ошиблись и какие уроки мы можем передать командам, планирующим аналогичный переезд.
Зачем менять платформу?
Jekyll сослужил нам хорошую службу. Однако спустя десятилетие он начинает устаревать.
Устаревшая инфраструктура. Jekyll — это генератор статических сайтов на базе Ruby, и за годы наша конфигурация обросла множеством пользовательских плагинов, вставок (includes) и соглашений. Создание новой функции часто ощущалось как обход ограничений платформы. Кроме того, в Coveo только наша команда использовала Ruby, что снижало потенциал для совместной работы. Наконец, поскольку экосистема Jekyll менее активна, функции, которые в более современных платформах Node.js доступны бесплатно в виде готовых пакетов, для Jekyll часто требовали дополнительных усилий при разработке.
Медленная обратная связь для авторов. Локальная пересборка занимала от трех до четырех минут. Горячая перезагрузка (hot reload) работала только для самых простых изменений, и даже тогда занимала около 20 секунд. Существенные изменения кода и изменения переиспользуемого контента вообще не подхватывались, требуя ручной пересборки. Короче говоря, авторы теряли время.
Низкая производительность. Наш статический сайт работал медленнее, чем должен был. Шаблоны страниц не соответствовали современным веб-стандартам, а блокирующие рендеринг ресурсы замедляли отображение страниц.
Информация рассредоточена по сайтам. Со временем наша документация распространилась. Для документирования библиотек Coveo Atomic и Headless мы использовали специализированные инструменты и генерировали для них отдельные сайты. Эти сайты имели собственную навигацию, поиск и внешний вид. Читателю, который хотел перейти от концепции к соответствующей справочной документации, приходилось пересекать границы сайтов. Это работало, но не было идеальным, и мы хотели скрыть эту сложность от читателей. Объединение документации в рамках сайта Jekyll было бы возможным, но сложным из-за упомянутой выше устаревшей инфраструктуры.
Сложный AsciiDoc. Большая часть нашего контента была написана на AsciiDoc, причем в разных вариациях. Поскольку разные авторы делали свой вклад в разное время, были приняты разные соглашения: как вложены и продолжаются списки, как пишутся примечания (admonitions) и выноски кода, как используются включения и переменные. Мы все дальше и дальше отходили от простого Markdown, который более стандартен для настройки в стиле «документация как код» (docs-as-code). Со временем мы фактически накапливали технический долг.
Выбор платформы с помощью созданных ИИ прототипов
Мы оценили четырех кандидатов: Rspress, Astro, Astro Starlight и Fumadocs.
С помощью ИИ-агентов мы создали рабочий прототип (Proof of Concept) на каждой платформе всего за несколько дней и оценили объем работы для каждого требования, которое не поддерживалось платформой «из коробки».
Мы также провели тестирование на реальном контенте. Вместо сайта типа «hello world» каждый прототип собрал реалистичный срез документации — около 6000 файлов. Это дало нам репрезентативную базовую линию для оценки времени сборки, запуска сервера разработки и масштабируемости.
Два варианта на базе Astro собрались быстрее всего: холодная производственная сборка всего набора заняла 43 секунды с Astro Starlight и 52 секунды с «чистым» Astro. Rspress справился за 1 минуту 28 секунд, а Fumadocs работал более 20 минут, так и не завершив процесс.
У Fumadocs были отличные возможности для авторов, но казалось, что он не сможет справиться с нашими масштабами. Чистый Astro работал быстро, но потребовал бы самостоятельной разработки боковых панелей, оглавления, поиска и тем оформления. Starlight оказался ближе всего к победителю: у него была самая быстрая сборка и наибольшее количество встроенных функций.
Мы выбрали Rspress по трем причинам:
- Опыт создания контента. Он занял первое место для авторов, не являющихся разработчиками, и имел удобные встроенные проверки на наличие битых ссылок и изображений, а также понятные сообщения об ошибках.
- Переносимость. Rspress использует стандартные компоненты React и плагины unified remark/rehype вместо проприетарных форматов и API. Если мы когда-нибудь снова решим переехать, большая часть нашей работы останется с нами.
- Достаточная скорость. Сервер разработки запускался за 20 секунд, горячая перезагрузка происходила практически мгновенно, а отставание от холодной сборки Starlight на 45 секунд было небольшой платой за больший контроль и более удобную среду для письма.
Как агенты исправили тысячи конвертированных страниц
Выбор платформы оказался самой легкой частью. Перенос более 5,000 статей был сложнее, особенно учитывая, что мы не хотели отвлекать авторов от их работы. Нашей целью был конвейер конвертации, который мы могли бы надежно запускать неделями во время перехода на новый сайт Rspress, в то время как авторы могли бы продолжать работу на сайте Jekyll без длительной заморозки контента. Именно здесь ИИ-агенты сыграли самую большую роль.
Сложность контента. Наша документация включает тысячи статей, написанных дюжиной авторов за десятилетие, а также сгенерированный справочный контент, глоссарии, примечания к выпускам (release notes) и перенаправления (redirects), уходящие корнями в прошлое. Каждая страница должна была быть перенесена в целости, каждый старый URL-адрес должен был продолжать работать, а каждая внутренняя ссылка должна была указывать на нужное место. В дополнение к нашему сложному нестандартному AsciiDoc, сайт Jekyll имел собственные кастомные расширения, такие как фрагменты для включения, теги аудитории, подстановка переменных и метаданные поиска.
Кастомный конвейер конвертации. Универсальный инструмент для преобразования AsciiDoc в Markdown не подошел бы. Мы создали специализированный конвейер конвертации, который превращает исходные файлы Jekyll в MDX. Он обрабатывает каждую нашу нестандартную конструкцию, разрешает включения и переменные, сопоставляет старые мнемоники (slugs) с новыми маршрутами, оптимизирует изображения и выполняет постобработку ссылок на глоссарий и справочник API. Конвейер покрыт тестами, и мы можем запускать его снова при каждом изменении исходных файлов.
Автоматизированные проверки качества. Чтобы определить, насколько точно работает конвертация, мы создали две взаимодополняющие проверки. Сравнение на уровне исходного кода сопоставляет каждый конвертированный файл MDX с его оригиналом в формате AsciiDoc. Проверка соответствия контента сравнивает каждую отрендеренную страницу на новом сайте с ее аналогом на старом и оценивает степень сходства их текста. Это превратило вопрос «выглядит ли новый сайт правильно?» в число, которое мы могли отслеживать, и в отчет, в котором точно указывалось, что именно нужно исправить.
Цикл: люди проверяют, агенты исправляют. Наибольший прирост эффективности дал союз агентов с этими отчетами. Мы запускали полные проверки и отправляли агентов на устранение проблем.
Агент брал сообщение о проблеме или целый их класс и исправлял инструменты: конвертер, логику федерации или вспомогательный модуль, например перезапись ссылок. Затем он собирал затронутые страницы локально и проверял результат, повторяя процесс итеративно, пока сообщаемая проблема не исчезала. Только после этого он подготавливал изменения для проверки кем-то из нас. Множество исправлений касалось страниц с самыми низкими оценками, например элементов списков, потерявших вложенность, или блоков, оказавшихся привязанными не к тому шагу.
Исправляйте инструменты, а не страницы. Агенты не занимались ручным редактированием конвертированного контента. Каждое исправление вносилось в конвертер, логику федерации или вспомогательный модуль, поэтому оно применялось ко всему массиву данных при следующем запуске конвейера, а сам конвейер оставался пригодным для повторного запуска на протяжении всей миграции.
Проверки и ревью людьми. Полные проверки занимали часы и предоставляли достаточный объем работы, чтобы нам не нужно было запускать их очень часто. Хватало нескольких раз в неделю. Кроме того, человеческое суждение было полезно для запуска агентов над наиболее ценными исправлениями и для выявления более глубоких структурных проблем. Особенно в начале проекта требовалось тщательное ревью, поскольку решения должны были принимать опытные авторы. Какой формат списков мы хотим принять в дальнейшем? Поддерживаем ли мы включения в списках? Что насчет списков во включениях и, если да, то как? Как быть с предупреждениями?
Куда уходило наше время. Вместо того чтобы исправлять проблемы по одной, мы тратили время на проверку пакетов изменений, подготовленных агентами, и запуск агентов для работы со следующим набором наиболее важных проблем.
Длинный хвост. Там, где этот рабочий процесс проявлял себя наилучшим образом, — это борьба с длинным хвостом краевых случаев ближе к концу проекта: тысячами мелких, специфических проблем, иногда возникающих лишь на горстке страниц. В этот момент проверки людьми часто проходили очень быстро, поскольку все крупные архитектурные решения уже были приняты, а агенты допускали мало ошибок. Мы могли оставлять их работать по вечерам или на выходные и получать хорошие результаты, возвращаясь за свои рабочие столы на следующее утро. За выходные агент мог выполнить работу, на которую у человека ушли бы недели.
Результат. В конце концов мы создали надежный конвейер конвертации, который использует сайт на Jekyll для ежедневного обновления сайта на Rspress, в то время как команда из 10 авторов продолжает создавать и редактировать статьи в первом. По мере развертывания нового сайта мы уверены, что как платформа, так и контент будут соответствовать нашим стандартам качества.
Что мы сделали не так
ИИ сделал эту миграцию возможной для команды нашего размера, но он не сделал ее полностью предсказуемой. Мы извлечем больше уроков по завершении этого проекта, но вот два вывода, которыми мы уже можем поделиться.
Мы недостаточно проанализировали массив данных на предмет всех шаблонов использования. Поскольку десяток авторов активно работал в репозитории почти десятилетие, ни у кого не было в голове всех сценариев использования, и мы обнаружили множество из них во время конвертации, несмотря на предварительное исследование с помощью агентов.
- Как вкладываются списки, предупреждения и включения?
- Вкладываются ли они рекурсивно?
- Как они парсятся в markdown по сравнению с asciidoc?
С высоты прошедшего времени мы бы потратили больше времени агентов в самом начале на изучение сайта на Jekyll для сопоставления всех подобных шаблонов перед массовой конвертацией.
В наших бенчмарках не учитывались сложность файлов и наши собственные плагины. Мы провели стресс-тестирование каждой платформы почти на 6000 страницах, но на этих страницах не было включений, ни один из этих прототипов не запускал пользовательские плагины, которые мы написали позже (например, включение контента), и они не обладали той сложностью страниц, с которой мы столкнулись на практике. Когда это произошло, время сборки существенно возросло. Миграция требовала частых пересборок, что нас замедляло. Агентам часто приходилось пересобирать весь сайт для запуска проверок во время итераций над исправлениями, поэтому чем дольше длилась сборка, тем больше времени уходило у агентов на внесение исправлений. Оглядываясь назад, мы бы провели бенчмаркинг со сложными статьями и, возможно, даже создали прототипы плагинов. Это позволило бы нам лучше оценить объем работы, необходимый для доведения конвертации контента до целевых стандартов.
Что получают читатели и авторы
Наиболее заметные изменения для читателей — это скорость и единый сайт. Более масштабное изменение скрывается за кулисами: теперь авторы могут быстрее обновлять документацию, а документация, которую быстрее обновлять, остается более точной и полной.
Более быстрый цикл обратной связи для авторов. Сервер для разработки запускается за секунды, и авторы видят свои изменения практически сразу после сохранения, не дожидаясь загрузки и не вызывая ее вручную. Встроенные проверки мертвых ссылок и изображений также выявляют ошибки на этапе сборки без необходимости ждать проверки CI.
Один сайт для всей нашей документации. Справочная документация для Headless, Headless React, Atomic и Relay, а также справочники по REST API теперь находятся на docs.coveo.com, а не на отдельных сайтах. Конвейер федерации извлекает каждый источник из npm, релизов GitHub, TypeDoc и OpenAPI, обнаруживает изменения и поддерживает страницы в актуальном состоянии. Читатели получают один сайт, одну навигацию и один поиск.
До и после:
Поиск и рекомендации на базе Coveo. Как и раньше, поиск и рекомендации статей на docs.coveo.com работают на базе Coveo. На новом сайте также добавлена командная палитра ⌘K, созданная с использованием Coveo Headless.
Скорость. Rspress выдает компактный статический HTML с современной сборкой и разделением кода, поэтому страницы загружаются и становятся интерактивными быстрее. Все функции сайта на Jekyll были перенесены, часто в более удобном виде, например темный режим и адаптивная верстка. Вот некоторые метрики до и после:
Семантические URL. Теперь URL описывают свое содержимое. Вместо непрозрачных числовых идентификаторов страниц вы получаете пути, которые подсказывают, где вы находитесь, еще до загрузки страницы, что помогает читателям, поисковым системам и всем, кто делится ссылкой. Сокращения по-прежнему поддерживаются везде, где это необходимо.
Попробуйте новую документацию
Новый сайт будет общедоступен по адресу beta.docs.coveo.com через несколько дней, в то время как docs.coveo.com продолжит обслуживать текущий сайт. Несколько недель спустя новый сайт переедет на docs.coveo.com. Каждый старый URL перенаправляет на новый адрес, поэтому ваши закладки и ссылки продолжат работать.
Миграция дает нам прочную основу. Благодаря современному стеку, быстрому циклу обратной связи и размещению всей документации в одном месте мы можем тратить меньше времени на борьбу с инструментами и больше — на то, что действительно важно: ясную, точную и полезную документацию.
Этот реплатформинг — первый шаг к значительному улучшению пользовательского опыта и архитектуры контента на docs.coveo.com. Следите за обновлениями.
