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

Цель

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

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

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

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

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

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

Структура

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

Генерация спрайта.
Использование спрайта.
Дебаг и превью через 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-документации.

Стиль

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

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

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

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

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

5.4 KiB Raw Permalink Blame History Unescape Escape