Привет! Меня зовут Павел Астахов, я работаю в департаменте системного анализа SM Lab. Сегодня расскажу про проектировочную документацию и её стандартизацию в нашей компании.
Причины внедрения стандартизации
Причина 1. Сотрудники
Департамент системного анализа появился в 2020 году: на тот момент нас было 50 человек в 20 командах; к 2024 году мы сильно разрослись и нас стало уже 260 системных аналитиков, которые трудились в 85 командах. Рост и увеличение масштаба департамента выявили проблемы, которые ранее не были видны и постепенно стали выходить на первый план.
В частности, стали появляться вопросы от системных аналитиков (особенно новеньких): «А какие вообще требования к постановке задачи?», «Как я пойму, что моя работа над задачей закончена и я могу передавать её дальше по потоку разработчику и тестировщику?» При запуске новых команд возникали следующие вопросы: «Как нам организовать свое пространство в Confluence?», «Что от нас ждут разработчики и тестировщики?», «А каково текущее актуальное состояние системы?»
Причина 2. Компания
И тут уже появились вопросы со стороны компании: «Как адаптировать по 60 человек в год так, чтобы ребятам было комфортно вливаться в рабочий процесс?»
Более того, увеличение числа сотрудников и команд вызвало увеличение взаимодействия между продуктами. Ребята стали часто наведываться друг к другу в пространство Confluence для того, чтобы почитать как работает та или иная система. И из-за того, что ребята работали в несколько разных подходах, ориентироваться в чужом пространстве было часто затруднительно.
А ещё у нас есть сотрудники, которые работают в компании уже более 10 лет и хотят перейти в другой продукт потому, что текущий знают уже досконально и хотят попробовать новую предметку и технологии.
Для того, чтобы все три процесса протекали гладко и не занимали много времени, мы решили стандартизировать всю документацию, построив единую систему ведения проектировочной документации, которая отражала бы все сведения, состояния и накопленные знания о всех наших системах на ландшафте компании «Спортмастер».
Первые шаги к решению проблемы: аудит и постановка целей
Первое, что мы сделали – провели аудит. Мы прошлись по нашим командам и сделали следующие выводы:
документация велась правильно там, где были хорошие инженерные практики;
то же самое касаемо структуры (однако в большинстве своём она велась стихийно);
инструменты для постановки задач использовались разные. В среднем это был либо Confluence, либо Jira, либо их некая смесь. Confluence был для нас предпочтительным вариантом, т.к. в Jira информация может уехать в бэклог, закрыться в задачах и потеряться. Смесь Confluence и Jira, когда ребята вели основную доку в Confluence, а доработки добавляли в Jira, тоже была таким себе вариантом: документация разъезжалась по разным системам, что не позволяло отслеживать её текущее состояние.
Проанализировав результаты работы, мы наметили следующие цели:
повысить характеристики постановок задач;
выработать систему проектировочной документации;
создать шаблоны.
Повышение характеристик постановок задач
Во-первых, поддержка актуальности документации: она должна отражать реальное состояние системы, которая постоянно дорабатывается и изменяется.
Во-вторых, точность и полнота. Системный аналитик должен предоставить полный набор данных о том или ином компоненте системы для того, чтобы все последующие специализации – будь то системный аналитик из другой команды или разработчик, или тестировщик – могли выполнять свои работы без дополнительных уточнений и требований.
В-третьих, нашей документацией пользуется широкий круг потребителей: от службы эксплуатации и дизайнеров до владельцев продуктов, поэтому она должна быть доступна и понятна.
Проектировочная документация
Для работы с шаблонами мы построили систему проектирования нашей документации:
связывание документов;
изменение документов;
раздел описательной аналитики.
Связывание документов делается для того, чтобы оценить влияние изменений на компоненты наших систем. Перелинковки – неотъемлемая часть процесса. Все необходимые вещи, которые следует уточнить, выполнены в виде гиперссылок: перейдя по ним, вы можете почитать следующую статью – совсем как в Википедии.
Как мы это делаем?
Каждый наш документ имеет свой уникальный код. Код формируется с помощью макроса Requirements и состоит из следующих блоков:
тип документа, например, АРІ;
код системы, например, MPSM;
мобильное приложение «Спортмастер».
Далее идет порядковый номер, который автогенерируется с помощью макроса Requirements. Мы используем эти коды для того, чтобы перелинковываться между системами.
Для того, чтобы проставлять связи между компонентами внутри системы, мы используем обычные ссылки Confluence, т.к. при использовании макроса Requirements Link серьезно снизило читаемость наших постановок.
Изменение документов влияет на такую характеристику, как актуальность и поддерживаемость: наши системы постоянно дорабатываются, регулярно вносятся изменения, и мы выработали для себя несколько способов работы с этими изменениями.
Наверное, самый простой и популярный способ, с которым сталкивалось большинство системных аналитиков, – это цвета и зачеркивания. Он для нас является основным (хотя и не самым удобным) как самый простой и доступный.
Работает это следующим образом. В постановке задачи изменяемый фрагмент выделяется цветом и зачеркивается. Новые требования дописываются тем же цветом ниже. В историю изменений вносится задача, по которой были выполнены изменения, и её описание. Далее это отправляется в разработку. Разработчик видит ту дельту, которую необходимо внести, видит задачу, по которой необходимо внести изменения. И, собственно, работает с постановкой задачи.
Есть и аналогичный способ – это блоки Old и New. Он является аналогом для цветов и зачеркиваний. По сути, это некое тегирование: мы заключаем предыдущую версию требований в блок Old, новую версию требований в блок New, закрашиваем цветом и также вносим в историю изменений. После передаем в разработку.
Если в системе мало доработок и эти доработки вносятся в одну функцию в одну единицу времени, мы можем описать все изменения технически в рамках Change Request. Далее запрос передается разработчику, который видит его единым документом – это проще, чем переключаться между разными постановками. И после того, как разработчик внес изменения в код, аналитика переносит данные из Change Request в постановку задач.
Структура раздела описательной аналитики влияет на понятность и доступность. Мы хотели стандартизировать правила размещения документации для того, чтобы ребята, приходя в чужое пространство, могли достаточно быстро навигировать по документации смежной команды и находить ту информацию, которая им необходима.
Структура раздела иерархическая. Пройдем по ней снизу вверх.
На самом нижнем уровне мы группируем наши документы согласно их функциональному назначению. К примеру, если у нас есть АРІ, то все АPI будут лежать в конкретном разделе Confluence, и если вам необходимо обратиться к АРІ, вы идете в раздел с АРІ. Но не все наши системы являются простыми: есть системы сложные (их на самом большинство), поэтому в случае, если система является сложной, в плоском списке затруднительно вести все АРІ, например, или экранную форму – их очень много, мы разбиваем нашу систему на функциональные блоки. Далее в рамках каждого функционального блока агрегируем информацию о тех компонентах, которые обеспечивают его работу. Например, если у нас есть корзина, то все API, доступные для корзины, будут лежать в разделе корзина, а все экранные формы, присущие разделу заказов, будут лежать в разделе заказов – это упрощает нашу навигацию.
Ну и группировка на уровне информационных систем. В ряде случаев наши продуктовые команды ведут не одну информационную систему, а несколько. В этом случае мы на самом верхнем уровне: уже разбиваем пространство на информационные системы, под ними идут функциональные блоки и под функциональными блоками конкретные компоненты.
В иерархической структуре можно увидеть и Change Request («запрос на изменения» – это, по сути, некий аналог Jira-задачи, который включает в себя смысл цели изменения, а также состав работ, которые необходимо выполнить для того, чтобы изменения можно было внести в систему). Если их не очень много, они хранятся на уровне информационной системы, если же их достаточно много, мы опускаем запросы под каждый функциональный блок.
А теперь перейдем к самому важному – шаблонам.
Шаблоны
Шаблон – это некий строительный кирпич, из которого мы собираем все описания наших информационных систем. Он обозначает тот набор знаний, который необходимо описать о компоненте и помогает нашим аналитикам ориентироваться в тех знаниях, которыми они должны владеть о системе, выявлять свои пробельные зоны и заполнять их.
В каждом шаблоне присутствуют следующие элементы:
Содержание. Для содержания используем макрос «Оглавление». Не скажу, что это самый важный общий элемент наших шаблонов, но это скорее дань хорошим практикам ведения технической документации, которая позволяет вновь пришедшему читателю быстро сориентироваться «А тот ли это документ и нужно ли мне в него погружаться более детально?»
-
История изменений. Важная часть наших документов, позволяет работать с изменениями и отслеживать их. Она состоит из ссылки на задачу, цвета правок, даты внесения изменений, их описания и автора. Как только мы видим, что статус задачи изменился на «Закрыт», это значит, что автор задачи или следующий аналитик, который пришел в постановку, должен перекрасить цвета изменений в дефолтный черный цвет, а записи в истории изменений перенести в архив.
Информация о документе содержит как раз тот самый уникальный код документа, набор описательных атрибутов, которые этому документу присущи, и они зависят от того типа документа, который мы описываем, а также списка всех потребителей, которые обращаются к этой постановки задачи для того, чтобы отслеживать на кого повлияют изменения, если мы этот документ поправим.
Теперь рассмотрим четыре наиболее популярных шаблона, которые используют 90-95% наших команд.
1. Graphical User Interface (GUI)
Graphical User Interface (GUI), или графический интерфейс пользователя. Используется для того, чтобы описывать все экраны, все графические интерфейсы, будь то экран мобильных, декстопных или веб-приложений.
Первый раздел – это входные-выходные параметры экранной формы. Они используются в тех случаях, если ваша экранная форма перед вызовом должна какие-то данные подгрузить, инициализироваться; например, вы хотите отредактировать какую-то запись из каталога записей, кликаете на нее и у вас открывается окно редактирования. Для того, чтобы окно редактирования открыло корректную запись, нужно передать ей параметры этой записи и она подгрузит данные. Ну или, например, у вас есть диалоговое окно, которое может вывести разные сообщения и текст на кнопках. Для того, чтобы можно было писать его единожды, а потом вызывать различными параметрами, можно использовать параметры формы.
Второй раздел – это экранные формы. Они могут работать в разных режимах и для того, чтобы не плодить сущности, можно всё описать в одной постановке. Например, экранная форма позволяет открывать запись в режиме просмотра или редактирования. Поведение полей и управляющих элементов в этих режимах может отличаться. Для этого мы вводим такой блок, как режимы работы экранной формы, описываем их, и в дальнейшем имеем возможность единожды описать экранный интерфейс и ту логику, которая присуща тому или иному режиму.
Третий раздел – это макеты. Мы ведем их в Figma и разбиваем на разделы для того, чтобы можно было в дальнейшем эти разделы описать. И, например, в макете на картинке строка поиска под цифрой 1 является отдельной постановкой задачи с отдельной логикой.
В структуре выбранной формы мы сослались на макет, прописав, что единичка – это строка поиска, и в описании приложили ссылку на ту постановку, которую необходимо реализовать. Разработчик может перейти и посмотреть, что этот компонент уже кем-то ранее реализовывался по определенной задаче, найти его в коде и приложить на нужный экран.
Ну и самый главный раздел – это описание элементов экранной формы. В принципе, описываем все достаточно подробно – до полей, как говорится. Все поля экранной формы, все управляющие элементы расписаны и внесены в табличку. Для них описаны источники данных, типы данных, форматы данных, размерности, значения по умолчанию и те действия системы, которые она выполнит при взаимодействии клиента с управляющим элементом.
С самым сложным шаблоном закончили. Поговорим об алгоритмах.
2. Algorithm (ALG)
Алгоритм – это один из тех шаблонов, который может использоваться в рамках других шаблонов, подтягиваться туда. С помощью него мы описываем интерфейсную логику, например, различные вычисления там. Были случаи, когда ребята описывали сложные вычислительные алгоритмы похожие на некий курсач, для описания логики интеграции и бизнеса которого использовали алгоритмы.
Выглядит он следующим образом – это просто текстовое описание в виде иерархического списка. Если алгоритм сложный, то разбиваем эти списки на подразделы. Иногда ребята применяют табличные описания, где для каждого шага используется строка таблицы.
Ну и для того, чтобы в некоторых алгоритмах упростить читаемость, мы применяем блок-схемы и диаграммы активности для визуализации алгоритмов. Везде их не вставляем, только там, где решения уже устаканенные и к этим алгоритмам часто обращаются разные потребители.
3. Data definition (DD)
С помощью определения данных мы описываем любые объекты хранения данных, будь то, например, бизнес-объекты, табличка «База данных» или некоторые сообщения, которые отправляем в брокеры.
Для описания используем следующие атрибуты:
наименование атрибута, которое присваиваем мы, обычно вкладывая в него бизнес-смысл. Если нам необходимо добавить наименование атрибута, которое придумал разработчик, у нас в таблице есть раздел физическая таблица, куда можно внести наименование таблицы и наименование соответствующего поля;
системы и источники, а также алгоритмы заполнения данных, если эти данные откуда-то в таблицу поступают, например, интеграция со внешней системой, вызов API или данные, которые поступают из экранной формы;
описание атрибута, его тип и обязательность и ключи, если это необходимо.
Обязательно прописываем логику заполнения таблицы, если эта таблица работает с интеграционными взаимодействиями или экранными формами.
4. Application Programming Interface (API)
Вот здесь будем в основном говорить про REST API, т.к. у нас в компании он является стандартом взаимодействия между системами.
При описании обязательно определяем заголовки, описываем параметры строки и пути, прописываем для этих параметров наименования, типы, обязательности, даем описания, что это за параметр ну и, соответственно, для тела запроса описываем то же самое, что мы ожидаем на вход и с какими типами параметров.
Также описываем ответы, которые ожидаем от нашего интерфейса в зависимости от ситуации, как успешные ответы, так и те, когда что-то пошло не так с добавлением альтернативных сценарииев. В большинстве случаев у нас в теле ответа есть специальный блог для сообщения об ошибках. Но в некоторых случаях, например, для каких-то исключительных ситуаций тело может отключаться, тогда тоже его отдельно опишем у себя в постановке на API.
Если необходимо выполнить преобразования данных, указываем, из каких внешних систем можно получить эти данные. Для разработчиков описываем алгоритм формирования ответа.
Результаты
Перед тем, как проанализировать полученные результаты, пара слов о тех сложностях, с которыми мы столкнулись в первую очередь.
Самым сложным было первичное сопротивление от ребят, привыкших работать по определенным подходам. Им, конечно, было сложно адаптироваться, но где-то через месяц-два они привыкли и стали нормально воспринимать те изменения, которые принесли в их команды.
Также потребовалось дообучить часть сотрудников, погрузить их в технические аспекты, поскольку не всегда все аналитики описывали тот набор информации о системе, который мы требовали теперь описывать для повышения точности и полноты. Было трудно, но в конце концов мы получили положительную обратную связь: ребята профессионально подросли, им стало проще работать.
Ну и, если посмотреть ретроспективно, мы понесли достаточно высокие трудозатраты на разработку этой системы и её внедрение – около года в рабочей группе из 10 человек.
Теперь о результатах. Мы провели опрос пилотных команд, и большинство ребят отметили, что качество ведения их документация улучшилось: точность и полнота подросла в 60% случаев, доступность и понятность документации достигли 85%, т.к. стало проще ориентироваться, навигироваться как в своей, так и смежных командах.
Хочу отметить, что на картинке со статистикой нет ответа «Все стало очень плохо», но в вопросе такой вариант ответа присутствовал и было радостно видеть, что никто его не выбрал.
Планы на будущее
Прежде чем делиться планами на будущее, поделимся небольшим бонусом о связывании документов.
Мы используем их для создания контекстных диаграмм, которые отображают, откуда ваш продукт получает данные, кто получает их из вашего продукта и, что немаловажно, с помощью каких методов.
В дальнейшем мы также хотим попробовать построить и схему ландшафта. Если мы все наши АРІ между собой перевяжем, сможем построить её достаточно быстро и в актуальном состоянии. А также есть идея попробовать использовать LLM для того, чтобы автоматизировать некоторые ежедневные рутины системного аналитика. В частности, ревью постановок. Более того, мы попробовали уже в наши шаблоны АРІ позакидывать и погенерить swagger-файлы и получилось достаточно неплохо, закидывая постановку с полным описанием. В чате GPT можно на выходе получить рабочий swagger-файл.