Начинайте с контента, а не со скриншотов темы
Демо генератора может выглядеть великолепно и при этом не подходить вашей документации. До сравнения тем перечислите, что система должна публиковать: длинные руководства, API reference, учебные материалы, сгенерированные страницы, версии, несколько языков, тысячи статей или смесь всего этого.
Затем опишите авторов. Инженеры, которые ежедневно редактируют Markdown в Git, и редкие эксперты, работающие через браузер, имеют разные требования.
Сравнивайте модель контента
Sphinx силён там, где важны перекрёстные ссылки, структурированные директивы, большие технические документы и расширяемость. MkDocs удобен для Markdown-first-процесса и относительно простой структуры сайта. Astro — более широкий content-focused web framework: он даёт больше контроля над layout, типизированными content collections, assets и routing, но команда берёт на себя больше ответственности за издательский продукт.
Задача не в том, чтобы назначить победителя, а в том, чтобы подобрать абстракцию под работу.
Посчитайте поверхность сопровождения
Посчитайте кастомные плагины, переопределения темы, шаги сборки и внутренние соглашения. Каждая кастомизация — будущая задача при обновлении. Система с меньшим количеством функций может быть дешевле, если больше вам не нужно; богатая система может быть дешевле, если заменяет набор самописного glue-кода.
До выбора попробуйте обновление. Важный вопрос не «можем ли мы это кастомизировать?», а «поймёт ли следующий сопровождающий, зачем мы это сделали?».
Прототипируйте сложные случаи
Соберите небольшой spike с самыми неприятными реальными требованиями: большой таблицей, reuse, локализацией, подсветкой кода, изображениями, redirect, поисковыми метаданными и длинной статьёй. Проверьте сборку на репрезентативном количестве страниц.
Не оценивайте генератор только по главной странице.
Оставляйте возможность миграции
По возможности отделяйте смысл контента от разметки конкретной темы. Предпочитайте обычный Markdown и хорошо определённые компоненты сотням случайных HTML-фрагментов. Метаданные держите в документированной схеме.
Генератор — инфраструктура, а не идентичность команды. Выбирайте то, что упрощает надёжную публикацию сегодня и оставляет разумный путь выхода завтра.
Практический разбор
Рассматривайте «Как выбрать генератор документации и не выбрать религию» как небольшое испытание, а не сравнение списков функций. Возьмите три реальных материала: простую страницу, страницу с кодом или структурированными данными и неудобный материал с навигацией, переиспользованием или локализацией. Прогоните все три через выбранный инструмент или подход и отдельно запишите, что стало проще, а какая новая стоимость сопровождения появилась.
Оценивайте повторяющуюся работу команды:
- понятен ли исходник автору без специальной подготовки;
- видит ли рецензент содержательный diff;
- сообщает ли сборка об ошибке так, чтобы было понятно, что исправить;
- можно ли переносить, локализовать и переиспользовать контент без ручной чистки.
Не награждайте инструмент за красивую демонстрацию, которую реальный контент не выдерживает. Хороший инструмент уменьшает неопределённость в написании, ревью и публикации. Если сложность просто переехала в конфигурацию, хрупкие плагины или память одного специалиста, это тоже часть цены.
Короткий редакционный чек-лист
- Начинайте с контента, а не со скриншотов темы. Демо генератора может выглядеть великолепно и при этом не подходить вашей документации.
- Сравнивайте модель контента. Sphinx силён там, где важны перекрёстные ссылки, структурированные директивы, большие технические документы и расширяемость.
- Посчитайте поверхность сопровождения. Посчитайте кастомные плагины, переопределения темы, шаги сборки и внутренние соглашения.
- Прототипируйте сложные случаи. Соберите небольшой spike с самыми неприятными реальными требованиями: большой таблицей, reuse, локализацией, подсветкой кода, изображениями, redirect, поисковыми метаданными и длинной статьёй.
