Привет, Хабр! На связи снова я, Егор Марюшко, архитектор решений в «Ростелеком Информационные Технологии» и основатель образовательного центра STENET school.

Весной я выступил на конференции «Второй Аналитический Курултай в Центральной Азии», которая прошла в прекрасном городе Алматы, Республика Казахстан, где рассказал о том, с чего начать и с помощью каких инструментов навести порядок в хаосе из требований и документации. Само выступление можно посмотреть и послушать здесь, ниже я приведу его текстовый вариант. Надеюсь, мой опыт окажется полезным многим читателям!

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

По результатам опроса, только 25% аналитиков считают, что в их проекте порядок с документацией.

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

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

Все артефакты я разделил на две категории: структурирующие и содержательные.

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

Содержательные артефакты — это множество однотипных артефактов, и в проекте постоянно появляются новые экземпляры данных артефактов.

Содержательные артефакты являются составными частями структурирующих артефактов. Структурирующие артефакты в свою очередь ссылаются на содержательные.

Структурирующие артефакты — что это и какими бывают?

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

Какие артефакты можно отнести к структурирующим?

1. Стартовая страница проекта (Welcome page)

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

2. Глоссарий

Это точка синхронизации понятийного аппарата всех участников проекта.

Народная мудрость: «Иди в глоссарий! Либо найдёшь ответ, либо добавишь ответ, когда найдёшь.»

Любые понятийно‑терминологические споры должны решаться через глоссарий. Например, если один ваш коллега использует термин «отправка», а другой — «отгрузка», то рассудить их можно с помощью глоссария, где мы смотрим обозначение каждого из терминов. Вполне вероятно, что оба говорят об одном и том же, просто разными словами. Например, в одном из проектов был случай, когда бизнес‑заказчик отказывался воспринимать «отгрузку», настаивая, что это «отправка». Нам пришлось для 10 тысяч пользователей в системе переименовать документ и обновить все бизнес‑процессы, чтобы можно было нормально коммуницировать с заказчиком. Глоссарий позволит избежать рассинхронизации. Когда вы говорите об одном и том же, но разными словами, возникают ошибки. Эти ошибки потом просачиваются в код, попадают к тестерам, и потом самое страшное — на продакшн.

По ссылке оставляю шаблон универсального сквозного проектного глоссария.

3. Реестр бизнес‑процессов

Любое требование всегда соответствует какому‑либо бизнес‑процессу в программном продукте. Не бывает требований, которые не были бы привязаны к бизнес‑процессу. Могут быть требования, которые связаны сразу со всеми бизнес‑процессами.

Для чего нужен реестр бизнес‑процессов? Благодаря ему мы видим, что умеет наша система. А также, изменяя какой‑то бизнес‑процесс, мы сможем увидеть, на какие артефакты нужно обратить внимание и какие требования нужно переосмыслить. Или, если мы меняем одно требование, сможем увидеть, на какие бизнес‑процессы это может повлиять.

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

Поэтому реестр бизнес‑процессов, особенно в крупных энтерпрайз‑проектах, вещь незаменимая. И чем крупнее компания, тем более сложную структуру бизнес‑процессов она будет иметь. Они будут делиться на домены, на поддомены, разделы, функции, подфункции, это может быть довольно крупным и длинным артефактом. У нас в «Ростелекоме» на одном из проектов в реестре бизнес‑процессов порядка 150 отдельных строк, где каждая строка — отдельный бизнес‑процесс. И на каждый из них приходится не один десяток требований и спецификаций, которые им соответствуют.

4. Модель предметной области

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

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

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

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

5. Реестр интеграции

Реестр интеграции позволяет быстро найти нужную интеграцию, видеть используемые технологии. Понимание интеграций становится все более важной частью профессии бизнес‑ и системного аналитика (системного — в первую очередь). На российском рынке уже тяжело найти вакансию системного аналитика, где не было бы в требованиях знаний о REST, SOAP, Kafka, брокерах сообщений. Время изолированных систем подходит к концу. Практически все системы интегрируются со всем, что есть вокруг. Даже самый простой калькулятор в смартфоне имеет интеграцию по обновлению своей же версии с, например, Apple Store или Play Market. Казалось бы, что там можно обновлять, математические законы 10 тысяч лет не меняются, но, тем не менее, интеграция есть, обновления прилетают.

Реестр интеграции — более технический артефакт, но он тоже структурирующий, так как структурирует взаимодействие нашей информационной системы с окружающим миром.

По ссылке делюсь примером такого реестра.

Что такое содержательные артефакты и какими они бывают?

Содержательные артефакты можно сравнить с кирпичиками, которыми мы заполняем каркас здания. Они несут основной контент и создают комплексную, всеобъемлющую документацию по проекту. К ним можно отнести: диаграммы, спецификации требований, описание бизнес‑объектов, описание интеграции. Содержательные артефакты могут быть очень разной детализации. Если без структурирующих артефактов можно жить, то без содержательных артефактов жить нельзя.

1. Шаблон спецификации требований

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

Когда мы работаем над шаблоном спецификации требований, важно определить состав спецификации. Будем мы писать user story или только use case? Будем ли мы рисовать диаграммы, sequence‑диаграммы или только BPMN? Будем рисовать диаграммы use case или нет? Мы самостоятельно определяем набор того, что нам нужно.

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

Часто бывает, что мы в шаблон пытаемся засунуть всё, что когда‑то слышали на конференциях или подсмотрели у кого‑то. Вам нужно сделать эталонный пример оформления этой спецификации, чтобы любой аналитик, взяв шаблон, не придумывал, как его заполнить, а мог зайти на страницу и посмотреть образец заполнения — как описать use case, с какой детализацией, как нарисовать диаграмму, какие ссылки сделать. Сочетание шаблона с примером его заполнения помогает быстро начать работу по созданию спецификаций даже новому в проекте сотруднику.

2. Шаблон диаграммы бизнес‑процесса

Бизнес‑процессы — неотъемлемая часть проектирования информационных систем. В первую очередь нужно выбрать графическую нотацию для моделирования бизнес‑процессов. У меня был опыт, когда в отделе из 10 бизнес‑ и системных аналитиков все рисовали бизнес‑процессы по‑разному: одновременно в ходу было три нотации. Мягко говоря, это был хаос. Чтобы его не допустить, обязательно определитесь с нотацией.

Дальше составьте соглашение о моделировании: какие элементы нотации вы используете и как всё должно выглядеть в целевом виде.

Потом выберите инструмент моделирования. Это может быть Gliffy, Draw.io, Visio или Business Studio, где есть и реестр бизнес‑процессов, и бизнес‑ценности, и много всего другого. Но важно, чтобы инструмент тоже был одним.

3. Шаблон бизнес‑объекта

В BABOK его называют словарем данных, когда каждый бизнес‑объект описывается в рамках своего атрибутивного состава. В шаблоне описания бизнес‑объекта вы по каждому атрибуту указываете:

• какой у него тип данных,

• обязательность / необязательность,

• граничные условия,

• пояснения

• и т. д.

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

4. Шаблон документирования интеграции

Для начала нужно выбрать инструмент, где вы будете описывать интеграции: Swagger, Confluence и т. д. Потом — определить, что будет входить в описание: перечень методов, описание атрибутов, маппинги и т. д. Всё это дает нам подробное описание интеграционных возможностей нашей информационной системы.

С чего же начать наводить порядок?

Это главный вопрос, который возникает у большинства. Приведу три простых правила наведения порядка.

1. Начинать можно с чего угодно.

   Лучше это делать либо с самого простого, либо с того, что вызывает больше всего проблем и болей в проекте. Здесь даже не нужно придумывать никакой стратегии. Увидели, что нет глоссария? Создали глоссарий, начали его наполнять. Нет стартовой страницы (Welcome Page)? Создали её. Увидели проблемы с интеграциями, каждый раз куча багов вылезает и дублирующие активности? Создали реестр интеграции.
   Просто начните наводить порядок ?

2. Поддержание порядка — это часть процесса работы.

   Не работает схема, сегодня сделать спецификацию, а завтра привязать её к своему структурирующему артефакту. Либо сегодня создать новый бизнес‑процесс, а завтра добавить в реестр бизнес‑процессов. Действия по поддержанию порядка должны быть непрерывными. Если вы прервались, то вы уже навели беспорядок.

3. Перфекционизм убивает порядок.

   Можно бесконечно долго придумывать идеальный шаблон или допиливать структуру бизнес‑процессов. Это не принесет пользы. А выпущенный в эксплуатацию драфт чего‑либо, который вы в дальнейшем, естественно, будете шлифовать, даст гораздо больше эффекта. Например, можно создать реестр бизнес‑процессов и уже потом эти бизнес‑процессы можно переименовывать, разделять, объединять, добавлять новые или удалять. Главное, что точка структуризации у вас уже есть.

Все артефакты, про которые я рассказал, не истина в последней инстанции, не обязательность. Это инструменты, которые вы можете принести в свой проект и модифицировать под себя, не изобретая велосипед с нуля. Если, например, у вас уже описаны структуры физических объектов в базе данных, то вполне возможно, что структура бизнес‑объектов вам уже не нужна.

Ещё один момент, который хотел бы подсветить: как справиться с противодействием во время внедрения изменений и их распространения среди аналитиков? На самом деле это решается достаточно просто.

Например, как внедрить шаблон чего‑либо? Мы выявили проблему, далее собираем рабочую группу из 3–5 человек, рабочая группа готовит первый вариант, драфт. Дальше драфт выносится на обсуждение, все оставляют к нему комментарии. Если есть противоречащие комментарии, то большинством выбирается тот формат, который больше нравится и лучше подходит. Такая компиляция знаний и комментариев принимается за отправную точку. Если кто‑то говорит, что всегда писал use case, а user story никогда не писал и не собирается, то вспоминаем про общую цель — стандартизацию документации. И тут человек либо соглашается с принятым большинством подходом, либо может искать команду и компанию где пишут use case. Так как возможность убедить команду в полезности use case у него была в рамках обсуждения, а последующее противодействие это уже саботаж.

Всем спасибо за внимание и до встречи в новых статьях!

В телеграм‑канале, где я делюсь знаниями и материалами по образованию в области бизнес и системного анализа и архитектуры (BA_SA_Arch_edu), мне можно задать любой вопрос. Приходите, буду рад пообщаться!