Сайт документации без кода: структура и сборка за вечер

Сайт документации без кода собирается по описанию структуры: какие разделы, какие страницы внутри и что лежит в боковом меню. Zugo генерирует навигацию, страницы и оглавление, проверяет сборку в песочнице и публикует по ссылке. Многостраничная документация собирается за несколько минут, дальше разделы добавляются правками.

Документация проваливается не из-за вёрстки. Она проваливается тогда, когда человек не может за десять секунд понять, в каком из разделов лежит его ответ, и уходит писать в поддержку.

Чем сайт документации отличается от блога?

Тремя вещами, и каждая меняет структуру проекта.

Порядок чтения. Блог читают от свежего к старому, документацию читают от простого к сложному. Значит на первом месте не последняя запись, а раздел «Быстрый старт», и порядок страниц в меню задаёте вы, а не дата.

Точка входа. В блог приходят на главную, в документацию попадают из поиска сразу на внутреннюю страницу. Отсюда требование: каждая страница должна быть самодостаточной. Заголовок объясняет, что это, первый абзац объясняет, зачем, и в боковом меню видно, где вы находитесь.

Срок жизни. Пост в блоге стареет и остаётся в архиве, страница документации устаревает и начинает врать. Поэтому дата обновления и явная версия продукта на странице это не украшение, а рабочая необходимость.

Как разложить разделы, чтобы в них не терялись?

По задачам пользователя, а не по устройству вашего продукта. Это главная развилка, и на ней ошибаются чаще всего.

Разложение по устройству продукта выглядит логично изнутри: «Модули», «Настройки», «API». Человек снаружи не знает ваших модулей, он знает свою задачу: подключить, настроить оплату, выгрузить данные. Оглавление, повторяющее внутреннюю архитектуру, заставляет читателя угадывать.

Рабочая схема из четырёх уровней:

Правило объёма: если раздел вырос больше чем до семи-восьми страниц, его пора делить. Меню, в котором двадцать одинаковых по весу пунктов, читается так же плохо, как отсутствие меню.

Какой промпт написать для документации?

Опишите дерево разделов явно. Билдер соберёт навигацию ровно по нему, и это тот случай, когда подробный промпт экономит несколько раундов правок:

Сайт документации для [продукт].
Слева боковое меню с разделами, справа оглавление текущей страницы.
Разделы и страницы:
1. Быстрый старт: установка, первый запуск, проверка что всё работает.
2. Руководства: [список задач по одной странице на задачу].
3. Справочник: [список сущностей, параметров, кодов ошибок].
4. Вопросы и решения: типовые проблемы, симптом и причина.
На каждой странице: заголовок, абзац «зачем это нужно», шаги,
блоки кода с кнопкой копирования, дата обновления.
Сверху поиск по страницам сайта.
Внизу страницы ссылки «предыдущая» и «следующая».
Светлая и тёмная темы, переключатель в шапке.

Три строки в этом промпте окупаются сразу. Кнопка копирования у блока кода, потому что без неё читатель выделяет мышью и захватывает лишнее. Ссылки «предыдущая» и «следующая», потому что документацию читают последовательно. Оглавление текущей страницы справа, потому что длинную страницу невозможно осмотреть иначе. Как формулировать такие требования, разобрано в гайде как писать промпт для AI-билдера.

Нужен ли поиск и как он работает?

Нужен, начиная примерно с пятнадцатой страницы. До этого меню справляется само.

Поиск в собранном сайте работает по тексту страниц на стороне браузера. Это значит: он находит совпадения по словам, работает мгновенно и не требует сервера, но он не понимает синонимов и опечаток. Человек, который ищет «отменить подписку», не найдёт страницу, где написано «прекращение оплаты».

Отсюда практический приём, который стоит одной правки: добавьте в конец страниц строку с другими формулировками той же задачи. Не ради поисковых систем, а ради собственного поиска. Страница «Отмена подписки» с припиской «также: отписаться, прекратить оплату, вернуть деньги» находится в разы чаще.

Второй приём это осмысленная пустая выдача. Если ничего не найдено, показывайте не пустоту, а три самые частые страницы и ссылку на контакт поддержки.

Где хранить тексты статей?

Два маршрута, и выбор зависит от того, кто пишет.

Прямо в сборке. Тексты лежат в проекте, правки идут через чат: «добавь в раздел «Руководства» страницу про экспорт данных с такими шагами». Просто и дёшево. Подходит, когда документацию ведёт один человек и обновления происходят раз в неделю.

В базе через Supabase. Страницы лежат в вашей таблице, сайт их читает. Появляется возможность править тексты без пересборки и пускать к ним нескольких редакторов. Осмысленно, когда документацию ведёт команда.

Есть и третий сценарий, который стоит держать в голове с самого начала: экспорт проекта в GitHub. Документация это тот тип сайта, который со временем чаще всего переезжает к разработчикам и начинает жить рядом с кодом. Код проекта принадлежит вам, и забрать его можно в любой момент, механика разобрана в гайде про экспорт приложения в GitHub.

Сколько стоит собрать сайт документации?

Кредиты списываются за действие. Одностраничная сборка стоит 6 кредитов. Многостраничный проект считается как платформа: 12 кредитов за первые три страницы и по 3 за каждую следующую. Правка стоит 3.

Режим Hi-Fi удваивает эти числа: сборка 12, правка 6. Для документации он почти всегда лишний: здесь ценится читаемость, а не визуальные эффекты.

Free даёт 5 кредитов, этого не хватает даже на одну сборку. Pro стоит $25 в месяц и даёт 200 кредитов, чего достаточно на каркас и на регулярные обновления. Business стоит $99 в месяц. Про устройство многостраничных проектов есть отдельный разбор: многостраничный сайт нейросетью.

Как понять, что документация работает?

По входящим вопросам, а не по числу страниц. Документация существует ради одной измеримой вещи: чтобы человек нашёл ответ сам и не написал в поддержку.

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

Первая стопка это проблема навигации и формулировок. Скорее всего страница называется вашими словами, а не словами пользователя, или лежит не в том разделе. Лечится переименованием и строкой с другими формулировками той же задачи.

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

Полезно завести на каждой странице вопрос «была ли страница полезной» с двумя кнопками и полем для комментария. Ответы приходят редко, но каждый из них указывает на конкретный абзац, который вводит в заблуждение. Если ответов накапливается много, их стоит хранить в базе и разбирать так же, как идеи на доске обратной связи.

Что билдер не сделает для документации?

Три честные границы.

Он не напишет документацию за вас. Он соберёт структуру, навигацию и оформление. Содержание страниц знаете только вы, и это девяносто процентов работы.

Он не подтянет описание API из кода. Автогенерация справочника из исходников или из схемы это отдельный класс инструментов. Здесь справочник пишется руками или переносится готовым текстом.

Он не ведёт версии документации. Разделение на «версия 1» и «версия 2» с переключателем это ручная работа: отдельные страницы и явная навигация между ними.

С чего начать?

Соберите каркас из трёх страниц: быстрый старт, одно руководство по самой частой задаче и страница вопросов. Это 12 кредитов. Дайте ссылку двум людям, которые продукт не знают, и посмотрите, где они застряли. Их вопросы и есть план следующих страниц, и он всегда точнее того, что вы придумали заранее. Начать можно с описания структуры на zugo.dev.