Создавайте интерактивные диаграммы как технический писатель

Одним из моих любимых инструментов технического писателя является построение диаграмм. Этот тип визуального контента не только помогает читателю лучше понять материал, но и позволяет писателю оживить технические детали творческим подходом.

Моя первая статья об интерактивных диаграммах привлекла столько внимания и положительных отзывов, что я решил продолжить изучение этой темы. В этой статье мы рассмотрим анимированные блок-схемы (с интерактивностью, конечно!), которые объясняют несколько сценариев в бизнес-логике программного обеспечения.

Когда дело доходит до описания бизнес-логики программного обеспечения, я обычно использую блок-схемы пулов. Они позволяют шаг за шагом вести читателя по процессу, подчеркивая, какая часть программного обеспечения отвечает за те или иные действия.

Представьте, например, мобильное приложение, в котором есть модуль, отвечающий за регистрацию пользователей. Этот модуль разделен на несколько классов, каждый из которых выполняет определенную деятельность в рамках процесса:

  • проверка данных пользователя
  • сжатие фото пользователя
  • получение адреса пользователя на основе геолокации пользователя
  • сохранение данных в серверное хранилище
  • и т. д.

Схема обзора может выглядеть следующим образом:

Однако, если нам нужно углубиться в процессы «Проверка данных пользователя», «Сжатие фото пользователя» и «Извлечение адреса пользователя», диаграмма может быть заполнена многочисленными вложенными условиями, длинными циклами, параллельными процессами и т. д.:

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

Но даже если это выглядит так, разделить эту громоздкую диаграмму на несколько диаграмм, разместить их на разных страницах и перемещаться между ними было бы отличным предложением. Однако иногда читатели считают неудобным перескакивать по страницам. Они хотят, чтобы все это было на одном экране в одно и то же время, чтобы за ним было легко следить.

Чтобы выполнить это требование, давайте попробуем сделать сложную в настоящее время схему более удобной для пользователя. Добавив несколько конкретных примеров успешных и неуспешных сценариев регистрации, мы можем плавно провести читателя через процесс, сосредоточив внимание на ключевых шагах.

Итак, то, чего мы хотим добиться, выглядит так:

Мы будем использовать draw.io в качестве инструмента для построения диаграмм.

Настройка фона

На фоновом слое вместе с самой диаграммой нам понадобится панель управления с кнопками для переключения между разными сценариями. Мы опишем один успешный сценарий и два сценария неудачной регистрации:

На данном этапе схема выглядит следующим образом:

Важные заметки

  • На фоновом слое кнопки, соответствующие трем сценариям, имеют непрозрачность = 50 %, а кнопка Нет сценариев имеет непрозрачность = 100 % и другой стиль, чтобы подчеркнуть, что на данный момент не выбран сценарий.

Успешный сценарий

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

1. На фоновом слое выберите все элементы (стрелки, действия, условия), которые участвуют в успешном сценарии.
❗Вы можете выбрать все элементы, а затем отпустить ненужные, потому что в успешном сценарии выполняются почти все действия.
Скопируйте выбранные элементы.

2. Перейдите на панель «Слои» и создайте новый слой с именем SuccessfulScenario.
Заблокируйте фоновый слой, разблокируйте слой SuccessfulScenario, и сосредоточить внимание на последнем.

3. Вставьте элементы, скопированные на шаге 1, в слой SuccessfulScenario. Измените цвета и стили элементов, чтобы выделить их:

4. На слое SuccessfulScenario выберите все элементы и переместите их прямо поверх соответствующих элементов на фоновом слое. После этого шага у вас не будет этого головокружительного разделения схемы.

5. Для стрелок поставьте числа, представляющие последовательность, в которой протекает процесс:

6. Создайте две новые кнопки на слое SuccessfulScenario:

  • один дублирует кнопку Успешный сценарий из Фонового слоя; эта новая кнопка имеет стиль, как если бы она была нажата;
  • один дублирует кнопку Нет сценариев из Фонового слоя; эта новая кнопка имеет стиль, как будто она выпущена.

Поместите эти кнопки поверх соответствующих кнопок на фоновом слое.

7. Под панелью управления создайте новую текстовую панель с описанием успешного сценария:

На данный момент мы уже достаточно выделили успешный поток и можем перейти к следующим сценариям. Однако анимацию я анонсировал в начале, так что давайте добавим динамику в диаграмму.

8. В верхнем меню draw.io выберите Extras -> Plugins. Нажмите кнопку Добавить и выберите параметр поток.

Перезагрузите страницу, чтобы активировать добавленный функционал.

9. На диаграмме переключитесь на слой SuccessfulScenario. В верхнем меню draw.io выберите Правка > Выбрать края.
Когда все стрелки на диаграмме отмечены как выбранные, перейдите на панель настроек справа и установите флажок параметр Анимация потока:

На данном этапе наш слой SuccessfulScenario выглядит следующим образом:

Важные заметки

  • Когда вы выбираете ребра на шаге 9, вы можете переместить все стрелки так, чтобы они не были точно там, где находятся фоновые стрелки. Если они будут прямо поверх фоновых стрелок, анимация будет не так заметна.

Неудачные сценарии

Идея для неудачных сценариев та же самая — мы помещаем новый слой для каждого неудачного сценария поверх фонового слоя.

1. На панели «Слои» сделайте видимым только фоновый слой и установите на нем фокус.

2. На фоновом слое выберите все элементы (стрелки, действия, условия), которые участвуют в первом неудачном сценарии.
Скопируйте выбранные элементы.

3. Перейдите на панель «Слои» и создайте новый слой с именем UnsuccessfulScenario1.
Заблокируйте фоновый слой, разблокируйте слой UnsuccessfulScenario1, и сосредоточить внимание на последнем.

4. Вставьте элементы, скопированные на шаге 2, в слой UnsuccessfulScenario1. Измените цвета и стили элементов, чтобы выделить их:

5. На слое UnsuccessfulScenario1 выберите все элементы и переместите их прямо поверх соответствующих элементов на фоновом слое.

6. Для стрелок поставьте числа, обозначающие последовательность, в которой протекает процесс:

7. Создайте две новые кнопки на слое UnsuccessfulScenario1:

  • один дублирует кнопку Неудачный сценарий 1 из Фонового слоя; эта новая кнопка имеет стиль, как если бы она была нажата;
  • один дублирует кнопку Нет сценариев из Фонового слоя; эта новая кнопка имеет стиль, как будто она выпущена.

Поместите эти кнопки поверх соответствующих кнопок на фоновом слое.

8. Под панелью управления создайте новую текстовую панель с описанием первого неудачного сценария:

9. В верхнем меню draw.io выберите Правка > Выбрать края.
Когда все стрелки на диаграмме отмечены как выбранные, перейдите на панель настроек справа и проверьте параметр Анимация потока.

Первый неудачный сценарий выглядит следующим образом:

Когда та же процедура выполняется для второго неудачного сценария, она будет выглядеть следующим образом:

Теперь мы закончили со сценариями и готовы к интерактивности.

Интерактивность

Теперь давайте добавим кликабельность нашим кнопкам для сценариев Successful и Unsuccessful.

Кнопка успешного сценария

1. На панели «Слои» щелкните слой SuccessfulScenario;

2. В нижнем меню панели «Слои» щелкните значок пера, чтобы открыть слой для редактирования;

3. Скопируйте идентификатор слоя:

❗ Также скопируйте идентификаторы слоев UncussessfulScenario1 и UncussessfulScenario2.

4. Переключитесь на фоновый слой диаграммы:

  • заблокировать и скрыть все остальные слои (SuccessfulScenario,UnsuccessfulScenario1, UnsuccessfulScenario2);
  • показать и разблокировать фоновый слой;
  • установите фокус на фоновый слой.

5. Щелкните правой кнопкой мыши кнопку Успешный сценарий и выберите Редактировать ссылку… во всплывающем меню:

6. В первой текстовой области вставьте следующий код:

data:action/json,{“actions”:[{“toggle”: {“cells”: [“layer_ID_toShow”]}},{“hide”: {“cells”: [“layer_ID_toHide1”, “layer_ID_toHide2”]}}]}
  • layer_ID_toShow — идентификатор слоя SuccessfulScenario, скопированный на шаге 3;
  • layer_ID_toHide1 — идентификатор слоя UnsuccessfulScenario1, скопированный на шаге 3;
  • layer_ID_toHide2 — идентификатор слоя UnsuccessfulScenario2, скопированный на шаге 3;

7. Нажмите на кнопку Применить:

Этот код покажет сценарий, когда читатели нажмут кнопку сценария Successful на фоновом слое, и скроет оба неудачных сценария.

Мы используем тот же подход для остальных сценариев. После добавления действий toggle и hide ко всем трем кнопкам сценария получаем следующий результат:

Единственное, что нужно сделать, это добавить кликабельности кнопке Без сценариев на каждом слое, кроме фонового.

1. Переключитесь на слой SuccessfulScenario диаграммы:

  • заблокировать и скрыть все остальные слои (UnsuccessfulScenario1, UnsuccessfulScenario2, background);
  • показать и разблокировать слой SuccessfulScenario;
  • установите фокус на слой SuccessfulScenario.

2. Щелкните правой кнопкой мыши кнопку Нет сценария и выберите Редактировать ссылку… во всплывающем меню:

3. В первой текстовой области вставьте следующий код:

data:action/json,{"actions":[{"hide": {"cells": ["layer_ID_toHide1", "layer_ID_toHide2", "layer_ID_toHide13"]}}]}
  • layer_ID_toHide1 — идентификатор слоя SuccessfulScenario, скопированный на шаге 3;
  • layer_ID_toHide2 — идентификатор слоя UnsuccessfulScenario1, скопированный на шаге 3;
  • layer_ID_toHide3 — идентификатор слоя UnsuccessfulScenario2, скопированный на шаге 3;

4. Нажмите на кнопку Применить:

Повторите шаги 1–4 этого раздела для слоев UnsuccessfulScenario1 и UnsuccessfulScenario2. Код кнопки остается одинаковым для каждого слоя.

Итак, вот оно! Мы закончили с нашей диаграммой:

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

Полезные ресурсы

XML-код для диаграммы доступен в этом содержании.