Документирование туров

Документирование туров — ключевой аспект поддержки и масштабирования интерфейсных сценариев. В проектах с использованием Shepherd.js грамотная фиксация структуры туров позволяет упростить сопровождение, ускорить онбординг разработчиков и обеспечить единообразие пользовательского опыта.

Структура описания тура

Тур в Shepherd.js представляет собой последовательность шагов, каждый из которых содержит настройки отображения и поведения. Для документирования важно фиксировать не только код, но и смысл каждого шага.

Базовые элементы тура:

  • Идентификатор тура
  • Назначение
  • Список шагов
  • Условия запуска
  • Зависимости от состояния интерфейса

Пример структурированного описания:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    cancelIcon: { enabled: true },
    classes: 'shepherd-theme-default',
    scrollTo: true
  }
});

Документация должна содержать:

  • описание цели тура
  • где и когда он запускается
  • какие пользовательские сценарии покрывает

Документирование шагов тура

Каждый шаг — самостоятельная единица, требующая детального описания.

Основные параметры шага

tour.addStep({
  id: 'step-1',
  text: 'Описание элемента интерфейса',
  attachTo: {
    element: '.selector',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    }
  ]
});

Что фиксировать в документации

1. Идентификатор шага

  • Уникальный
  • Осмысленный (например: profile-settings-button)

2. Назначение

  • Какую часть интерфейса объясняет
  • Какую задачу решает

3. Привязка (attachTo)

  • CSS-селектор
  • Позиция (top, bottom, left, right)

4. Контент

  • Текст подсказки
  • Возможные HTML-элементы

5. Кнопки

  • Названия
  • Поведение (next, back, cancel, кастомные функции)

Формат документации

Рекомендуется использовать единый формат, например Markdown или JSDoc-подобный стиль.

Пример описания шага

### Шаг: profile-settings-button

**Описание:** Объясняет кнопку перехода к настройкам профиля  
**Селектор:** `.profile-settings`  
**Позиция:** bottom  
**Текст:** Кликните для изменения настроек профиля  
**Кнопки:**  
- Далее → следующий шаг  
- Отмена → завершение тура  

**Условия отображения:**  
- Пользователь авторизован

Группировка и модульность

В крупных приложениях туры разбиваются на модули:

  • onboarding
  • dashboard
  • настройки
  • административные функции

Пример модульной структуры

export const dashboardTour = () => {
  const tour = new Shepherd.Tour();
  
  tour.addStep(...);
  
  return tour;
};

Документация должна отражать:

  • принадлежность тура к модулю
  • зависимости от других туров
  • порядок запуска

Документирование логики и условий

Туры редко являются линейными. Часто используются условия:

  • проверка авторизации
  • наличие данных
  • состояние UI

Пример

if (user.isAdmin) {
  tour.addStep(adminStep);
}

В документации фиксируется:

  • условие показа шага
  • альтернативные сценарии
  • поведение при невыполнении условий

События и жизненный цикл

Shepherd.js предоставляет события, которые важно документировать:

  • start
  • show
  • hide
  • complete
  • cancel

Пример

tour.on('complete', () => {
  console.log('Тур завершен');
});

Документация должна включать:

  • какие события используются
  • какие действия выполняются
  • влияние на состояние приложения

Версионирование туров

При изменении интерфейса туры требуют обновления. Без версионирования возникает рассинхронизация.

Подходы:

1. Версия в коде

const TOUR_VERSION = '1.2.0';

2. Хранение версии в localStorage

localStorage.setItem('tourVersion', TOUR_VERSION);

3. Документирование изменений

## Изменения

### v1.2.0
- Добавлен шаг для новой панели фильтров

### v1.1.0
- Обновлён текст шага onboarding

Связь с UX-документацией

Туры — часть пользовательского опыта, поэтому документация должна синхронизироваться с UX-описаниями:

  • пользовательские сценарии
  • CJM (Customer Journey Map)
  • прототипы интерфейса

Важно фиксировать:

  • на каком этапе пользователь видит тур
  • какую проблему он решает
  • ожидаемый результат

Автоматизация документации

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

Подходы:

1. Аннотации в коде

/**
 * @step profile-settings-button
 * @description Переход к настройкам профиля
 */

2. Генерация Markdown

Скрипты могут извлекать шаги и формировать документацию.

Частые ошибки

Отсутствие описания логики

  • шаг есть, но неясно зачем

Неактуальные селекторы

  • интерфейс изменился, документация — нет

Дублирование шагов

  • одинаковые шаги в разных турах без общей базы

Отсутствие условий отображения

  • непонятно, когда шаг появляется

Практика ведения документации

Эффективный подход включает:

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

Минимальный набор для каждого тура:

  • цель
  • список шагов
  • условия запуска
  • зависимости
  • версия

Интеграция с командной разработкой

Документирование туров облегчает:

  • передачу задач между разработчиками
  • тестирование
  • работу дизайнеров и аналитиков

Рекомендуется:

  • хранить документацию в репозитории
  • привязывать изменения к задачам (например, через commit messages)
  • использовать code review для проверки туров

Тестирование и соответствие документации

Документация должна отражать реальное поведение тура.

Проверяется:

  • корректность шагов
  • соответствие текстов
  • наличие всех условий
  • актуальность селекторов

Автоматизированные тесты могут:

  • проверять наличие DOM-элементов
  • запускать туры в headless-браузере
  • валидировать последовательность шагов

Грамотно оформленная документация туров превращает Shepherd.js из простого инструмента подсказок в полноценную систему сопровождения пользовательского опыта, устойчивую к изменениям интерфейса и масштабированию проекта.

Оглавление