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

Что Notion делает правильно

Быстрый и гибкий редактор. Полезные представления баз данных. Хорош для нетехнической документации.

Где Notion даёт сбой

Нет интеграции с git. Документация хранится в проприетарной базе данных Notion, оторванной от кодовой базы. Расхождение документации с кодом практически неизбежно.

Привязка к платформе. Экспорт в markdown неаккуратен. Проприетарные блоки становятся неопределёнными. Ваша документация — в заложниках.

Только облако. Self-hosted Notion не существует. GDPR, требования к размещению данных — заблокированы.

Производительность при масштабировании. Большие рабочие пространства работают медленно. Плохое ранжирование в полнотекстовом поиске.

Цены при масштабировании. $8/пользователь/месяц. Команда из 20 человек = $1 920/год только за документацию.

На что обращать внимание

  1. Настоящая двусторонняя интеграция с git
  2. Self-hosting
  3. Вывод в markdown-first формате
  4. Веб-редактор
  5. Публикуемая документация
  6. Фиксированные тарифы

Сравнение вариантов

Valoryx: git — это и есть хранилище. WYSIWYG-редактор. Единый бинарный файл. 5 редакторов бесплатно. Публикация документации встроена. Wiki.js: Self-hosted, приоритет базы данных, git опционален. Docusaurus: Чистый git, нет веб-редактора. Confluence: Корпоративный, Atlassian, нет git. Outline: Self-hosted, чистый редактор, нет git, требует PostgreSQL + Redis.

Скрытые издержки Notion

Расхождение документации с кодом. Болезненная миграция. Переключение контекста. Проблемы с поиском.

curl -fsSL https://valoryx.org/install.sh | sh
docplatform init --workspace-name "My Docs" --slug my-docs
docplatform serve