Статьи с меткой: Контент-модели
Sphinx, MkDocs, Astro и другие генераторы оптимизированы под разные модели контента и команды. Сравнивайте авторский процесс, расширяемость, локализацию и стоимость сопровождения, а не красоту демо и длину списка функций. Демо генератора может выглядеть великолепно и при этом не подходить вашей документации.
Структура, удобная на пятидесяти страницах, может развалиться на пятистах. Стройте навигацию вокруг задач пользователя, типов контента и устойчивых понятий, а не вокруг оргструктуры компании. Небольшой набор документации способен пережить почти любую навигацию.
Описание OpenAPI позволяет генерировать точную структуру справочника, но разработчику всё равно нужны концепции, сценарии, аутентификация, примеры и восстановление после ошибок — то, чего одна схема объяснить не может. OpenAPI отлично описывает операции, параметры, структуры запросов и ответов, статус-коды и повторно используемые схемы.
Согласованность в масштабе создают контент-модели, терминология и повторяемые паттерны, а не просьба выучить огромный style guide. Важные правила нужно кодировать в схемах и компонентах. Небольшая команда может держаться на общих привычках и прямой редактуре.