Где вести техническую документацию продукта
Взгляд со стороны разработчика
Кто мы?
Команда одного из продуктов Иксоллы, Чат-платформа. Если кратко — мы помогаем соединять людей. Пользователь, у которого возникли проблемы при оплате, пишет в саппорт. Разработчик игры обращается с вопросами к аккаунт-менеджеру. Наша команда предоставляет инструменты для связи всем участникам диалога.
Чат-платформа — сложный продукт с большим количеством проектов. Помимо основного продукта — Чата Иксолла, у нас есть виджет для работы с пользователями, бот для категоризации обращений, сервис для работы с интеграциями сторонних мессенджеров и большие планы по реорганизации и оптимизации всего этого счастья.
Мы стараемся решать DevOps-вопросы своими силами, поэтому все настройки CI/CD и Kubernetes доступны нам для внесения изменений.
Как не потеряться?
Чтобы не запутаться в этом зоопарке проектов и технологий, наша команда старается вести документацию. В компании стандартом является Confluence, и в какой-то момент пришло понимание, что мы из него выросли.
Минусы Confluence
- Большое загромождение результатами спринтов, записями встреч и прочей “менеджерской” информацией.
- Плохая реализация спейсов и поиска. Для того, чтобы найти интересующую информацию, особенно, когда не помнишь точную строку, приходится выполнить неслабый квест.
- Нет возможности описать API или нарисовать UML-диаграмму
Что делать?
Мы решили перебрать имеющиеся альтернативы для работы с технической документацией, оценивая их по ряду критериев:
- Удобство наполнения и навигации
- Синхронизация данных
- Поддержка UML (PlantUML, Mermaid)
- Возможность вставки API (Swagger, Open API)
- Возможность полного или частичного экспорта (PDF)
- Стоимость
Можно всех посмотреть?
Google Docs, One Note, Notion, Evernote, etc.
Данные продукты объединяет одно — они хороши только для написания статей. В них удобный редактор, вставка изображений и много отличных фичей. Когда же дело касается технической стороны, начинаются проблемы.
GitBook
Наиболее заточенный под техническую документацию продукт, свой редактор с кучей возможностей, синхронизация через GitHub, вставка API, примеров кода. Нет UML-диаграмм. Платный.
Archbee
Повторяет функциональность Notion, при этом есть возможность вставки API, кода, UML. Платный и имеет неприятное свойство зависать через какое-то время.
Docsify.js
Бесплатный, легкий, с кучей плагинов. Своего редактора нет, но есть поддержка Markdown. UML-диаграммы, Swagger через плагин. Полная настройка заняла 2 часа.
Docute
Внешне похож на Docsify.js, удобная базовая настройка, возможность сборки через Webpack.
Orchid
По описанию вроде неплохо, но написан на Java, что вызывает опасения в возможности поддержки. У демо-страницы не завелась админка.
А также
В итоговую таблицу не попали еще около 15 инструментов, в которых отсутствует 2 и более требований
Практика
Пока что мы остановились на Docsify.js. Множество плагинов, простая настройка, быстро запускается. Альтернативный вариант — Docute — протестируем чуть позже, когда перенесем документацию. Но это уже другая история
