Привет, я Вячеслав — руководитель отдела маркетинга ispmanager. Мы создаем сложный программный продукт, для которого нужна документация. Использовали Confluence, но решили поменять ПО — еще до того, как Atlassian ушел из РФ.  

Рассказываю, почему решили мигрировать, какие альтернативы тестировали, как запустили свой аналог и не скатились в «продуктовую пропасть». А еще поделюсь, что пошло не по плану и почему мы отказались от идеи продвигать продукт на коммерческой основе.

Мигрировать нельзя остаться

Популярная причина миграции с Confluence — сложность с оплатой после ухода Atlassian с рынка РФ. У нас с этим не было проблем, но были другие запросы — уход Atlassian добавил мотивации принимать решение о миграции быстрее =) 

Мы продаем панель управления — ниша достаточно узкая. SEO-запросов немного — большинство из них упираются в услуги хостинга, которые мы не предоставляем. Поэтому семантическое ядро маленькое — хотелось его расширить за счет индексации страниц с документацией.

Почему решили мигрировать с Confluence:

• Технические трудности из-за ухода Atlassian из РФ — в приложение не получилось добавить поддомен в зоне .ru — конструкция rudocs.ispmanager.com вместо привычного docs.ispmanager.ru нас не устраивала. 

• Необходимость расширить семантическое ядро. В статьях на поддомене «прячутся» SEO-ключи — с их помощью мы планировали расширить семантическое ядро. Поэтому стояла задача перенести контент на хост — чтобы документация стояла на одном сервере вместе с сайтом, и у нее был адрес example.com/doc вместо doc.example.com. С Confluence так сделать не получилось — его можно разместить только на поддомене.

Выбираем готовое решение

Собрали список требований от команды, что нам нужно от аналога Confluence:

• Установка на хост — главное требование.

• Удобная миграция из Confluence без потери содержимого.

• Понятный редактор статей — язык разметки Markdown, inline-стили. Например, выделение текста, курсив, списки.

• Возможность работать со структурой статей — менять уровни и работать с деревом статей. 

На начало 2022 года были доступны несколько отечественных вариантов — попробовали разные. Например, тестировали EvaWiki — приложение работало медленно, страницы загружались долго. Девопсы не одобрили — архитектура у EvaWiki на тот момент была  «монолитная», нам это грозило большой нагрузкой на сервер и медленной работой сайта.

Посмотрели на рынок и поняли — it’s time to delat’ svoi product. Так уже сделали крупные компании — например, Яндекс запустил Yandex Wiki, Ростелеком — систему управления проектами «Яга». Приступили к работе.

Давайте сделаем как в Confluence 

Опыт создания веб-приложений у нас есть — на сайте ispmanager уже работает фичреквест и форум, который мы написали с нуля на базе open-source решений. 

За основу взяли технологии: 

• Фреймворк Laravel для сайтов и веб-приложений.

• Админку на базе Orchid — Open-source решение для административной части сайта.

• MySQL (MariaDB) для баз данных. 

Рядом с фичреквестом на хосте у нас лежал актуальный сайт на Drupal — туда же мы планировали разместить документацию. Под этот «зоопарк» искали архитектуру, которая сможет нормально работать. 

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

Кодим, релизим и катимся в продуктовую пропасть

К работе приступили впятером: я, два веб-разработчика, DevOps и дизайнер. Позже присоединился тестировщик. 

Над названием продукта долго не думали, отталкивались от узнаваемого бренда ispmanager — получилось ispmanager Docs, а внутри компании прижилось сокращение iDocs.

Как выглядел процесс работы до первого деплоя:

• Написали парсер для Confluence и закатили туда дамп пространств из Confluence — в процессе потеряли половину контента. Потратили еще несколько дней —  доделали парсер, мигрировал текст, но потерялись картинки. Confluence хранит изображения в своей базе или подтягивает с URL — пришлось «перевозить» картинки в хранилище S3 и оттуда подтягивать их через подмену URL по маске. 

• Сделали административную часть приложения — настраивали создание статей, статусы, систему ролевого доступа, редактор. Мы использовали open-source, но все нужно было собрать вместе и подогнать под наши нужды.  

• Разработали архитектуру сайта и настроили маршрутизацию. Например, пользователь попадал на сайт и перенаправлялся в нужный раздел, который определял бэкенд.  

• Запустили выкатку обновлений с помощью CI/CD — раньше у нас его не было. Со временем научились выкатывать отдельные элементы системы: доку, сообщество, основной сайт. 

• Взяли свежий дамп актуальной доки и раскатили его на стейджинг. Все шло как по маслу — нажали заветную кнопку и запустили деплой. 

Разгребаем последствия деплоя

С какими проблемами мы столкнулись после деплоя: 

Страницы выдавали ошибку 404. Мы уходили с поддомена в хост, поэтому важно было проставить редиректы. Оказалось, мы сделали это недостаточно хорошо — около 20% редиректов, выставленных по маске rudocs.ispmanager.com/* поехали по бороде не проставились.

Причину нашли в парсере, когда сравнили старые и новые URL — он поменял генерацию русских слов в английской раскладке и «pol-zovatelya» превратились в «polzovatelya».  

В результате нашли старую структуру URL и проставили редиректы на уровне документации — мы предусмотрели возможность проставить 301 редирект из интерфейса iDocs. Транслитерацию в итоге сделали так же, как было в Confluence. 

Все починили примерно за неделю — в результате iDocs научили собирать URL после парсинга, как это делает Confluence. 

Появилась ошибка «Поиск не работает» — поиск работал только по названию статьи и ее описанию. Из-за этого репрезентативность выдачи стремилась к нулю.

Помимо этого, поиск оказался очень перегруженным. А еще статьи выдавались по степени совпадения, а не актуальности. Поэтому старые материалы по устаревшим версиям продукта упорно лезли в первые строки выдачи.

Дизайнер и веб-разработка доделали поиск, улучшили релевантность и докрутили интерфейс. Появилась возможность выбрать, по каким пространствам искать — например, по корневым директориям с документацией ispmanager 6, SSL-сертификатами и другими. 

Как выглядит поиск по пространствам:

После первого деплоя iDocs довольно быстро поняли, что продукт сырой — предстоит еще много работы, коллеги это подтвердили =)) 

Что еще доработали в iDocs :

• Докрутили работу со статьями — добавили предпросмотр статей, исправили ошибки, из-за которых не сохранялся текст в блоках и некорректно отображался код. 

• Добавили возможность мигрировать из Confluence по API. Теперь не нужно делать дамп и загружать его в парсер — iDocs все подтягивает по API.

• Сделали глобальный лог изменений. 

Что получилось

Дизайн iDocs сделали в светлой и темной теме. В статье рассказали, как уже разрабатывали темную тему для панели ispmanager.

Как выглядит пользовательский интерфейс iDocs:

Как выглядит iDocs в админке:

Стремились сделать интуитивно простой интерфейс — сейчас в iDocs понятная структура статей по уровням и удобные инструменты для оформления.

Как выглядят инструменты:

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

Как выглядит оглавление внутри статей:

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

Результаты

Сделали полноценный продукт для документации и базы знаний — получилась достойная альтернатива Confluence, которую мы смогли разместить на хосте.

Цель разработки iDocs — расширить семантическое ядро с помощью индексации страниц с документацией на основном домене. 

Как изменилась посещаемость сайта ispmanager:

Почему не стали вкладывать деньги в развитие iDocs

Изначально мы писали продукт для себя — не было цели развивать iDocs на коммерческой основе. Позже мы хотели попробовать вывести его на рынок. Но не срослось. 

Почему решили не продвигать iDocs:

• Маленький рынок — сложно посчитать объем. Многие крупные компании уже сделали для себя похожие решения, а маленькие игроки используют бесплатные программы — например, Media.Wiki, Wiki.js, DokuWiki. 

• Конкуренция на зарубежном рынке — «бороться» с Confluence трудно.

• Издержки — чтобы начать продавать iDocs, нужно вложить в продукт около 10 миллионов рублей. В бюджет входят задачи: разработать механизмы обновлений клиентских установок и учета срока лицензий, закрыть код, организовать техподдержку, упростить установку ПО, провести кастдевы с аудиторией.

• Длинный срок окупаемости — бюджет для выхода на рынок относительно небольшой, но срок окупаемости получился более 3 лет. В текущей экономической ситуации это не выглядит разумной инвестицией — есть способы окупить такую сумму быстрее. Например, расширить географию продаж флагманского продукта — панели управления ispmanager.

Для компании важно развивать продукт с понятным рынком и сроком окупаемости, поэтому от идеи продвигать iDocs «в люди» мы отказались. 

Но развитие iDocs на этом не остановилось — продолжили работу и регулярно докручиваем фичи для внутренних потребностей. Несмотря на то что продукт делали для себя, партнеры уже его купили =)

Я не считаю проект провальным — iDocs полностью закрыл потребность ispmanager в ПО для документации и базы знаний. А благодаря партнерам мы отбили издержки на первичную разработку. 

К тому же мы осознанно не дали скатиться проекту в «продуктовую пропасть» — сначала изучили спрос, сделали расчеты и решили не выходить на рынок. Все по-взрослому =)

Если вы уже пользуетесь собственными или готовыми аналогами Confluence — делитесь впечатлениями, обсудим в комментариях.