mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-09-16 04:30:18 +03:00
85 lines
5.4 KiB
Markdown
85 lines
5.4 KiB
Markdown
# Правила гайдов быстрого старта
|
|
|
|
## Цель
|
|
|
|
Гайд должен помочь читателю как можно быстрее создать 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-документации.
|
|
|
|
## Стиль
|
|
|
|
Писать для пользователя, а не для разработчика библиотеки.
|
|
|
|
Использовать короткие, прямые и практические формулировки.
|
|
|
|
Сначала объяснять пользу или цель шага, затем показывать действие.
|
|
|
|
Не использовать воду, рекламные формулировки и технические термины, которые не помогают выполнить инструкцию.
|
|
|
|
Не начинать документ с перечисления сгенерированных компонентов или особенностей реализации.
|