mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 04:40:17 +03:00
79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
# Правила гайдов быстрого старта
|
||
|
||
## Цель
|
||
|
||
Гайд должен помочь читателю как можно быстрее создать SVG-спрайт и использовать его в своём приложении.
|
||
|
||
Спрайт является главным результатом. Компоненты и другие сгенерированные файлы описываются только как средства его использования.
|
||
|
||
## Область гайда
|
||
|
||
Каждый гайд посвящён одному exact mode.
|
||
|
||
В гайд включаются только действия и особенности, относящиеся к этому mode. Нельзя переносить в него поведение других сборщиков, фреймворков или modes.
|
||
|
||
Все технические утверждения необходимо проверять по реализации соответствующего adapter.
|
||
|
||
## Структура
|
||
|
||
Гайд состоит из трёх основных частей:
|
||
|
||
1. Генерация спрайта.
|
||
2. Использование спрайта.
|
||
3. Дебаг и превью через Viewer.
|
||
|
||
Первая строка после заголовка должна объяснять, что это инструкция по быстрому созданию SVG-спрайта и для какого приложения она предназначена.
|
||
|
||
## Примеры
|
||
|
||
Все примеры внутри гайда должны составлять один последовательный сценарий.
|
||
|
||
Пути, имена, команды, импорты и названия сгенерированных API должны соответствовать друг другу и фактическому результату генерации.
|
||
|
||
Во всех гайдах используются согласованные примеры:
|
||
|
||
- исходные SVG находятся в `assets/svg-icons`;
|
||
- спрайт создаётся в `assets/app-icons`;
|
||
- конфиг записывается в JSON;
|
||
- имя спрайта в конфиге — `app`.
|
||
|
||
## Зависимости
|
||
|
||
В разделе генерации нужно явно показать ключевое преимущество: для создания и использования спрайта пакет не требуется добавлять в зависимости проекта.
|
||
|
||
Viewer описывается отдельно как необязательный инструмент разработки. Установка или подключение пакета допускается только в разделе Viewer и только способом, подходящим текущему mode.
|
||
|
||
## Содержание
|
||
|
||
Гайд должен содержать только минимальный рабочий путь:
|
||
|
||
- структуру проекта;
|
||
- конфиг;
|
||
- команду генерации;
|
||
- автоматическую генерацию перед запуском и сборкой, если она необходима;
|
||
- подключение иконки;
|
||
- базовую настройку размера и цветов;
|
||
- подключение Viewer.
|
||
|
||
Особенности mode добавляются только тогда, когда без них пример не работает или работает неправильно.
|
||
|
||
## Технический шум
|
||
|
||
Не нужно описывать внутреннее устройство генератора, сгенерированных файлов и сборщика.
|
||
|
||
Не нужно перечислять альтернативные конфигурации, дополнительные API, редкие сценарии и ограничения, не относящиеся к быстрому старту.
|
||
|
||
Подробности должны оставаться в reference-документации.
|
||
|
||
## Стиль
|
||
|
||
Писать для пользователя, а не для разработчика библиотеки.
|
||
|
||
Использовать короткие, прямые и практические формулировки.
|
||
|
||
Сначала объяснять пользу или цель шага, затем показывать действие.
|
||
|
||
Не использовать воду, рекламные формулировки и технические термины, которые не помогают выполнить инструкцию.
|
||
|
||
Не начинать документ с перечисления сгенерированных компонентов или особенностей реализации.
|