# Правила гайдов быстрого старта

## Цель

Гайд должен помочь читателю как можно быстрее создать SVG-спрайт и использовать его в своём приложении.

Спрайт является главным результатом. Компоненты и другие сгенерированные файлы описываются только как средства его использования.

## Область гайда

Каждый гайд посвящён одному exact mode.

В гайд включаются только действия и особенности, относящиеся к этому mode. Нельзя переносить в него поведение других сборщиков, фреймворков или modes.

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

## Структура

Гайд состоит из трёх основных частей:

1. Генерация спрайта.
2. Использование спрайта.
3. Дебаг и превью через Viewer.

Первая строка после заголовка должна объяснять, что это инструкция по быстрому созданию SVG-спрайта и для какого приложения она предназначена.

## Примеры

Все примеры внутри гайда должны составлять один последовательный сценарий.

Пути, имена, команды, импорты и названия сгенерированных API должны соответствовать друг другу и фактическому результату генерации.

Во всех consumer-гайдах используются согласованные примеры:

- исходные SVG находятся в `assets/svg-icons`;
- спрайт создаётся в `assets/app-icons`;
- конфиг записывается в JSON;
- имя спрайта в конфиге — `app`.

`standalone@server` является исключением: quick start использует config-less CLI,
исходные SVG находятся в `./icons` временного worker workspace, output создаётся в
текущем каталоге, а mode, name и input передаются флагами одной команды. Server
config упоминается только как дополнительный вариант; подключение из consumer
может использовать обычный JSON config соответствующего mode.

## Зависимости

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

Viewer описывается отдельно как необязательный инструмент разработки. Установка или подключение пакета допускается только в разделе Viewer и только способом, подходящим текущему mode.

## Содержание

Гайд должен содержать только минимальный рабочий путь:

- структуру проекта;
- конфиг либо полный config-less CLI-вызов для `standalone@server`;
- команду генерации;
- автоматическую генерацию перед запуском и сборкой, если она необходима;
- подключение иконки;
- базовую настройку размера и цветов;
- подключение Viewer.

Особенности mode добавляются только тогда, когда без них пример не работает или работает неправильно.

## Технический шум

Не нужно описывать внутреннее устройство генератора, сгенерированных файлов и сборщика.

Не нужно перечислять альтернативные конфигурации, дополнительные API, редкие сценарии и ограничения, не относящиеся к быстрому старту.

Подробности должны оставаться в reference-документации.

## Стиль

Писать для пользователя, а не для разработчика библиотеки.

Использовать короткие, прямые и практические формулировки.

Сначала объяснять пользу или цель шага, затем показывать действие.

Не использовать воду, рекламные формулировки и технические термины, которые не помогают выполнить инструкцию.

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