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-документации.
|
|||
|
|
|
|||
|
|
## Стиль
|
|||
|
|
|
|||
|
|
Писать для пользователя, а не для разработчика библиотеки.
|
|||
|
|
|
|||
|
|
Использовать короткие, прямые и практические формулировки.
|
|||
|
|
|
|||
|
|
Сначала объяснять пользу или цель шага, затем показывать действие.
|
|||
|
|
|
|||
|
|
Не использовать воду, рекламные формулировки и технические термины, которые не помогают выполнить инструкцию.
|
|||
|
|
|
|||
|
|
Не начинать документ с перечисления сгенерированных компонентов или особенностей реализации.
|