При использовании нового приложения или веб-сервиса у пользователей могут возникнуть различные проблемы. И некоторые из них попытаются решить свою проблему с помощью поиска ответа по документации. Но не всегда справочная информация легкодоступна и уж тем более удобна для навигации по ней.
Возможное решение
Если вы задумывались, как упростить вашим пользователям доступ к документации, то можно попробовать сервис Mintlify, который позволяет хранить пользовательскую документацию по проекту в GitHub и предоставить к ней удобный доступ на выделенном домене.
Начало работы
Прежде всего, для работы в Mintlify вам потребуется авторизоваться под вашей учёткой на Github. Это позволит хранить всю созданную документацию в репозитории и при необходимости работать с ней через привычный разработчикам git.
Сам же сервис представляет собой что-то типа любого онлайн-заметочника с несколькими разделами:
- Overview с последними обновлениями по проекту;
- Editor — непосредственно редактор документации;
- Analytics со статой по посещаемости вашей документации;
- AI Chat — ну куда же без него.
Также при первом переходе в редактор вас попросят установить приложение для GitHub. Речь, если что, не про Git или десктопную версию GitHub, а про установку Mintlify в веб-версию GitHub.
Последнее, что стоит учесть перед началом работы с Mintlify, — веб-версия сервиса находится в стадии беты. А нормальная работа гарантируется только через CLI. Я не разработчик, и в душе не знаю, как этим CLI пользоваться, поэтому ниже я расскажу именно про веб-версию.
Я расскажу именно про редактор. С остальным, думаю, и так всё очевидно.
Возможности редактора
Редактор представляет собой что-то среднее между работой над кодом и обычным текстовым редактором на том же GitHub.
От кода здесь есть возможность переключения между ветками и отправкой коммитов. А в остальном это обычный редактор, но с возможностью переключения между тремя режимами: WYISWYG, Markdown и сравнение различий.
Также для загрузки любых файлов потребуется создать файловую структуру, как при разработке приложения.
В целом при работе в редакторе у меня не возникло каких-то трудностей. Правда, иногда для корректной работы приходилось обновлять страницу. А ещё все изменения в режиме реального времени уходят на GitHub. С одной стороны, это странно с учётом логики работы с системами контроля версий. А с точки зрения работы над текстовым документом как будто бы и норм.
Вы можете добавлять любую необходимую информацию, править форматирование, добавлять блоки кода и делать всё, что вы обычно делаете с документацией. Тут вопросов нет.
Проект на GitHub с готовой документацией выглядит так, а так выглядит её опубликованная веб-версия.
Пожалуй, самая полезная (кому как) фишка Mintlify и опубликованной веб-версии документации — возможность поиска по ней. Правда, в этот момент за поиск отвечает ИИ, который может найти и выдать нужный вам результат. А может и не выдать, даже если есть документы с совпадением по поисковому запросу.
Что можно настроить
Конечно, вы можете подключить собственный домен, на котором пользователи смогут просматривать документацию.
Кроме этого, вы можете перенести документацию в другой проект на GitHub или подключить свой GitLab и хранить информацию в нём. Ещё можно настроить авторизацию пользователей для просмотра документации.
Есть поддержка аддонов (правда, их всего два, и их нельзя отключить).
Управление правами доступа к исходному коду документации и API-ключи тоже не забыли.
Стоимость
У Mintlify есть урезанный бесплатный тарифный план, которого должно хватить независимым разработчикам. Сюда же входит возможность работы на собственном домене.
Платные начинаются от $150 в месяц и добавляют множество полезных штук: собственные стили CSS и JS, увеличенное количество ответов AI, продвинутая аналитика и многое другое.
Но нужно учесть, что поддержка GitLab, авторизации пользователей и прочих секурных штук доступна только на тарифе Enterprise.
Выводы
Честно говоря, у меня большие сомнения в необходимости использования Mintlify на вашем, пусть даже маленьком, проекте. И не потому, что сервис плохо работает, а просто зачем?
Создать подобную веб-страничку с документацией для ваших пользователей можно десятком аналогичных сервисов, включая тот же Notion. Единственная полезная (и то не факт) фишка Mintlify — поиск по докам с помощью искусственного интеллекта.
С другой стороны, если вы искали подобный сервис, то я не вижу никаких причин не попробовать Mintlify.