Привет, дорогие читатели Хабра! С вами на связи Алина Шилова, старший аналитик направления разработки цифровых продуктов T2. Я занимаюсь системным анализом уже не первый год и хочу признаться, что за время своей работы нарисовала какое-то чудовищное количество диаграмм. Ведь все мы, аналитики, призваны нести в мир эту магию кубиков и стрелочек. Кто-то может ненавидеть подобное скрупулёзное занятие, кто-то – наоборот медитирует в поисках идеального расположения элементов на полотне. Но так или иначе без диаграмм не обойтись ни одному аналитику.
Диаграммы, как и любые визуальные инструменты, помогают буквально увидеть систему в ее динамике и взаимодействии с внешним контуром, наглядно представляя ее границы, внешние интеграции и внутреннюю структуру. Диаграммы не только ускоряют процесс согласования требований, но и уменьшают вероятность ошибок и недопонимания в процессе разработки. Они позволяют говорить на общем языке даже тем специалистам, чьи знания и опыт лежат в разных плоскостях. Именно поэтому эффективные процессы работы с диаграммами являются одним из факторов успеха проекта. И наоборот: если в диаграммах на проекте царит хаос, то это прямой путь к разночтениям и, как следствие, багам в системе.
В этой статье я хотела бы поделиться своим опытом и наблюдениями, которые помогли оптимизировать процесс создания диаграмм в технических спецификациях на нашем проекте. Безусловно, это частный опыт, а не волшебная таблетка на все случаи жизни. Но все же из него можно вынести несколько универсальных рекомендаций, которые могут быть применимы в любом проекте.
Коротко о проекте
Кратко погружу в контекст, чтобы дальше было понятно, чем были обусловлены возникшие на нашем проекте проблемы и способы их решения. Скажем так, обозначить точку А, из которой мы, пробираясь через тернии к звездам, отправились в ту самую желанную точку Б.
В целом проект, на котором я работаю в T2, как и используемые в нем инструменты, довольно стандартны для отрасли. Мы разрабатываем веб-приложение с микросервисной архитектурой, интегрируемое с другими внешними системами с помощью REST API или брокера сообщений. Техническую документацию пишем в Confluence. Инструменты для создания диаграмм в компании не регламентированы, поэтому аналитики вольны выбирать, в чем им удобнее работать – Microsoft Visio, Miro, Sparx Enterprise Architect и т.п. Вот тут и начинается самое интересное.
Рецепт идеального инструмента
Какая вообще разница, где рисовать диаграммы? Казалось бы, схема есть схема, просто изображение. Читателю ТЗ абсолютно безразлично, в каком инструменте она нарисована, ведь он видит финальное изображение. И с этим не поспоришь – читателю действительно все равно. А писателю? То есть аналитику, который пишет ТЗ. Давайте разбираться.
После того как аналитик нарисовал диаграмму и добавил ее в ТЗ, жизненный цикл этой диаграммы еще не заканчивается. На протяжении развития продукта в архитектуру неизбежно вносят изменения, которые необходимо отображать на схеме – это значит, что встает вопрос оптимальной процедуры ее актуализации. Если на проекте работает несколько аналитиков, то задачи могут передаваться от одного аналитика к другому, а значит, доступ к исходникам диаграммы должен быть у всех. И даже если в вашей команде один аналитик, нужно позаботиться о том, чтобы в случае ухода из команды он не унес исходники диаграмм с собой в могилу в своем личном аккаунте Miro, доступа к которому не будет у новых сотрудников. И вот он первый и очень важный ингредиент нашего блюда (=критерий выбора инструмента) – возможность общего доступа и совместной работы над артефактами.
Итак, предположим, что доступ к исходнику у вас есть – теперь нужно внести изменения. Ранее вы нарисовали диаграмму, скажем, в Microsoft Visio, экспортировали ее как изображение и вставили в ТЗ картинку в формате png. Чтобы внести изменения, вам потребуется снова открывать Visio, менять диаграмму там, экспортировать новый файл изображения и перезаливать его в ТЗ (неважно, на какой платформе вы ведете документацию). Звучит не так критично, как наличие общего доступа, но лишних действий довольно много. А мы же боремся за эффективность. Отсюда напрашивается вывод (и вторая составляющая нашего аналитического винегрета): инструмент создания схем в идеале должен быть интегрирован с инструментом ведения технической документации. Так, чтобы редактировать диаграммы прямо по ходу написания ТЗ, а не таскать непонятно откуда какие-то исходники. Это ли не мечта любого аналитика?
Важнейший побочный эффект актуализации любых артефактов в процессе разработки – это версионирование этих самых артефактов (в нашем случае диаграмм). Очень хочется, чтобы была возможность посмотреть историю версионирования. Потому что хорошо знать ответ на вопрос, как работает система сейчас, но еще лучше – понимать, как она работала раньше и почему развивалась именно в выбранном направлении. Это поможет, с одной стороны, не возвращаться к анализу тех подходов, которые уже однажды были отвергнуты, а с другой стороны, отслеживать в исторической перспективе, как менялись интеграции при поиске каких-либо зависимостей с другими системами.
Приправим все это бесплатным лицензированием и наличием внятной документации/поддержки/коммьюнити – чем угодно, что может помочь разобраться в работе инструмента и не оставаться один на один с бездушным интерфейсом системы. Вуаля – идеальный инструмент для рисования схем готов!
А теперь без шуток - где такое найти?
Когда мы выявили критические потребности аналитика в процессе создания и сопровождения диаграмм, мы обозначили основные критерии поиска инструмента, а это уже – полпути к успеху. Далее следует отталкиваться от инструмента, в котором ведется техническая документация (ведь мы помним, что хотим рисовать диаграммы во встроенном редакторе непосредственно в ТЗ). И вот на этом моменте наши с вами пути вероятно расходятся, потому что потребности у каждого проекта разные, и инструменты в компании используются разные. Но чтобы перед глазами был пример, я бы хотела показать, как мы организовали процесс работы с диаграммами на нашем проекте в Confluence с помощью плагина для работы с draw.io.
Draw.io (также Diagrams.net) - это бесплатный онлайн-сервис, который предназначен для визуализации данных, моделирования процессов и системного проектирования. Имеет лицензию Apache 2.0 и относится к open-source решениям. Draw.io Diagram – это макрос, позволяющий встраивать объекты, созданные в графическом редакторе draw.io, на страницы Confluence.
Если вы планируете переиспользовать одну и ту же схему на разных страницах внутри своего пространства Confluence, то для начала необходимо выбрать, какая страница будет основной, т.е. будет содержать исходник схемы. Именно на этой странице будет происходить ее редактирование. На остальных страницах будет вставляться своеобразная ссылка на исходник схемы. Т.е. визуально схема также будет отображаться, но при попытке отредактировать ее система будет перенаправлять вас на страницу с исходником.
Логично выбирать в качестве основной страницы для исходника схемы родительский раздел. В нашем случае – это спецификация, в которой описывается создание микросервиса, она является головной в разделе про данный микросервис. Все остальные доработки микросервиса описываются на вложенных страницах. И эти вложенные страницы переиспользуют схему-исходник.
Чтобы создать схему-исходник, выполните следующие действия:
1. В панели инструментов нажмите на плюс для добавления макроса и в раскрывающемся списке выберите «Другие макросы».
Откроется окно «Выбор макроса».
2. В окне «Выбор макроса» перейдите на вкладку «Схемы и изображения» и выберите макрос draw.io Diagram.
Откроется окно с выбором шаблона.
3. На этом шаге вы можете выбрать пустой шаблон (Blank) или шаблон нужного вам типа диаграммы (например, на вкладке UML есть основные диаграммы, используемые в системном анализе).
После выбора шаблона откроется редактор платформы Draw.io, встроенный в страницу Confluence.
4. Нарисуйте нужную вам схему. При необходимости обратитесь к руководству пользователя Draw.io.
5. После завершения работы над схемой нажмите на кнопку «Опубликовать».
6. Введите название диаграммы и нажмите на кнопку «Сохранить».
Созданная в редакторе диаграмма отобразится на странице Confluence.
7. Если требуется внести изменения в диаграмму, перейдите в режим редактирования страницы, а затем кликните двойным щелчком мыши на диаграмму. Откроется редактор draw.io.
Чтобы переиспользовать на другой странице схему-исходник, выполните следующие действия:
1. В панели инструментов нажмите на плюс для добавления макроса и в раскрывающемся списке выберите Embed draw.io Diagram.
Откроется окно «Встроить диаграмму draw.io».
2. Выберите нужную диаграмму на вкладке «Недавние диаграммы» или, если вы рисовали ее давно, перейдите на вкладку «Поиск» и найдите там по названию.
3. Нажмите на кнопку «Добавить».
Диаграмма отобразится на странице Confluence.
4. Если требуется внести изменения в диаграмму, перейдите в режим редактирования страницы, а затем кликните двойным щелчком мыши на диаграмму.
Откроется окно «Встроить диаграмму draw.io».
5. Нажмите на кнопку «Изменить страницу владельца». В новой вкладке откроется страница Confluence, содержащая схему-исходник в режиме редактирования.
6. Нажмите двойным кликом мыши на схему-исходник и в открывшемся редакторе draw.io внесите нужные изменения, и опубликуйте обновленную схему.
7. Сохраните страницу со схемой-исходником.
8. Сохраните страницу, на которой переиспользуется схема.
Но и это еще не все
В этой статье описан базовый функционал создания схем и диаграмм в графическом редакторе draw.io и их переиспользования на страницах Confluence. Однако раз уж мы взялись спекулировать кулинарными метафорами (да простят меня читатели, которые никак не могут вырваться на обед), как обычную печеную картошку можно превратить в изысканный ресторанный гратен Дофинуа, так и с помощью возможностей плагина draw.io можно довести процесс создания диаграмм до максимальной степени изощренности. Например, на нашем проекте мы активно работаем со слоями. Это позволяет переиспользовать в постановках на доработку микросервиса общую схему микросервиса, но при этом выделять только дорабатываемые элементы схемы. Так читающему сразу видно, какие изменения претерпит микросервис в результате доработки. Но, кажется, мы с вами и так уже немного засиделись, поэтому, если есть желание погрузиться в тему работы со слоями – пишите в комментариях. На мой взгляд, она вполне заслуживает отдельной статьи.
Выводы
Описанный подход к работе с интеграционными диаграммами позволил нам на проекте решить все проблемы, озвученные во вводной части, а именно:
Проблема | Решение |
Исходник схемы хранится у автора схемы и должен передаваться другим участникам команды, которым требуется вносить изменения в схемы. | Исходники хранятся на серверах Confluence вместе со страницами, доступ к ним есть у всех участников команды. |
При изменении схемы требуется переделывать скриншот и заменять его по тексту спецификации. | Изменения можно вносить непосредственно на странице Confluence, нет необходимости делать скриншоты схем. |
Если схема переиспользуется на нескольких страницах, то при изменении схемы необходимо отслеживать, чтобы она была обновлена везде и вручную заменять скриншоты во всех спецификациях. | Изменения вносятся в одном объекте и автоматически подтягиваются во все страницы, где используется этот объект. |
В рамках одной спецификации виден только исторический срез - схема, актуальная на момент написания спеки. Нужно переходить в родительский раздел, чтобы увидеть текущую схему микросервиса (и надеяться, что у аналитика дошли руки обновить ее там). | С помощью слоев в рамках одного объекта можно проследить в динамике все хронологическое изменение схемы вплоть до текущего состояния, не прыгая между разделами Confluence. |
Как видим, данный подход повышает степень актуальности документации, при этом сокращая трудозатраты аналитика на поддержку интеграционных схем, что и доказывает опыт внедрения такой практики на нашем проекте. А всем, кто еще в процессе, хочу пожелать успехов в поиске своего секретного ингредиента!
