Документация как инструмент управления проектом

Привет, меня зовут Василий Белькович, я аналитик в Банке ДОМ.РФ. В этой статье хочу рассказать о процессе работы с документацией, выстроенном в нашей команде. Вначале несколько слов о нас и о том, чем мы занимаемся. Команда состоит из двух десятков человек, включает в себя все базовые роли: аналитики, разработчики, тестировщики, DevOps-инженеры, специалисты технической поддержки. Главная наша задача – это сопровождение, доработка и поддержка централизованной корпоративной IDM-системы (системы, управляющей доступом пользователей).

На первый взгляд кажется, что идентификация, аутентификация и авторизация пользователей являются рутинной. При этом её замечательно автоматизируют различные open source-системы, присутствующие на рынке. В них масса базовых кейсов работает «из коробки». Зачем в таком случае нужны разработчики и при чём тут документация? Если речь о построении SSO между пятью-шестью АС с типовыми требованиями к управлению пользователями, то действительно на этом статью можно закончить.

Но когда вы сталкиваетесь с необходимостью в рамках группы компаний интегрировать несколько сотен разрозненных АС с разными типами учётных записей (сотрудники, партнёры, клиенты, потенциальные клиенты), разными подходами к управлению пользователями (начиная от самостоятельной регистрации и заканчивая заведением УЗ через менеджера в офисе) и разными потоками аутентификации (доменная, 2-FA, ЕСИА, Qr-код, внешняя БД, запросы к CDI или АБС), то становится очевидной необходимость отлаженного процесса разработки и документирования нового функционала.

Мы особенно остро это почувствовали, когда пришлось подключать две сотни АС из компании группы, работавших на отдельной IDM. Базовая проблема состояла в отсутствии актуального описания подключений, требующих переноса. Пришлось распутывать сложный клубок взаимосвязей, чтобы постепенно (группами) переключить все АС на нашу IDM, не прерывая соответствующих бизнес-процессов. Данное событие послужило толчком к разработке подхода, описанного ниже.

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

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

1. Сокращение количества обращений от внешних команд по типовым вопросам подключений.

2. Предоставление актуального описания всех кастомных доработок в IDM

3. Поддержание нескольких версий одной статьи, описывающей какую-либо кастомную функцию.

4. Оптимизация взаимодействий между всеми членами команды.

5. Помощь в определении границ функционального тестирования при релизе обновлений.

6. Автоматизация отчётов по подключенным АС.

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

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

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

Третья часть содержит описание всех доработок, произведённых в IDM. Именно за счёт этой части документации решается большинство поставленных нами задач.

Теперь рассмотрим отдельно каждую из трёх частей документации.

В ней мы сосредоточили статические статьи, в общем описывающие нас:

· наши цели и задачи;

· описание IDM в целом;

· описание и схемы наших стендов;

· перечень типовых подключений.

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

Первая часть документации обновляется вручную. Триггером для обновления служит появление нового (или модификация старого) варианта сценария. В среднем потребность в обновлении возникает раз в полгода.

Главный секрет первой части документации состоит в том, что все сценарии в ней описаны кратко и лаконично. В них нет массы технических подробностей, но они дают чёткое представление об основных возможностях нашей IDM. Конечно, к такому описанию мы пришли не сразу. По началу сценарии были максимально подробными. Содержали детальные sequence-диаграммы, описание всех исключительных ситуаций, правила логирования, журналирования и т.д. Но очень быстро стало понятно, что поток обращений за консультациями по базовым вопросам (Как к вам подключиться? А вы умеете так? А вы поддерживаете это?) не уменьшается. Тогда мы пересмотрели подход и описали все сценарии в виде простых графических схем с минимальным требуемым описанием.

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

Благодаря автоматизации процесса переноса подключения из песочницы в контур интеграционного тестирования (публикации) у нас появилась возможность автоматически формировать вторую часть документации. За перенос отвечает модуль нашей собственной разработки. Суть процесса в том, что после одобрения обращения о переносе модуль создаёт копию подключения в контуре интеграционного тестирования и по заранее определённому шаблону через API вики-системы создаёт новую страницу с описанием этого подключения. Ключевыми полями на странице являются:

· номер обращения для публикации;

· наименование АС, которой принадлежит данное подключение;

· область sso (перечень систем, с которыми должна поддерживаться единая точка входа);

· ссылки на выбранные сценарии (подключения, аутентификации, управления пользователями и сессиями);

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

Таким образом получаем список всех подключенных АС и их взаимосвязи. О том, как его не хватало, я писал во введении. А установка меток разработанных компонентов позволяет формировать матрицу, отображающую какие из наших доработок какими АС используются. Колонки – это разработанные компоненты, а строчки – это подключенные АС. Приведём пример. Допустим, что есть 10 АС, использующих для аутентификации OTP-код, направляемый в СМС-сообщении. Формирование и отправка этого кода реализована через разработанный нами провайдер исполнения. В какой-то момент возникает необходимость в обновлении (дополнении) его логики работы. И благодаря описанной выше матрице сразу становится понятен перечень АС, потенциально попадающих под влияние. А значит, определяется объём тестирования, необходимый для релиза доработки.

В итоге вторая часть документации позволила решить две последние задачи из списка.

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

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

1. Аналитик заводит задачу в таск-трекере, кратко описывающую для разработчика суть нового функционала. Затем он создаёт новую страницу в разделе описания компонентов, выбрав подходящий подраздел и соответствующий шаблон (пример шаблона на Рис.1). Обычно шаблон включает в себя несколько разделов. Первый – описание назначения и бизнес-требований для нового компонента. Второй – описание логики работы нового компонента. Третий – опциональный, описание настроечной части. Четвёртый – опциональный, описание серверной части (БД, Классы, Модули и т.д.). Пятый – опциональный, описание фронтовой части с визуальными макетами. Шестой – опциональный, описание правил журналирования (логирования). Ключевыми полями во всех шаблонах являются:

· номера задач из таск-трекера, в рамках которых создаётся или модифицируется данный компонент;

· поле «Статус», в нём устанавливается значение «Аналитика»;

· поле «Индивидуальная метка», в нём указывается уникальная строка, которая будет проставляться на страницы всех сущностей, использующих этот компонент.

Также аналитик заполняет справочник, связывающий новый компонент и сущности IDM, такие как Потоки, Клиенты, Федерации, Идентификационные провайдеры (Рис.2).

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

1. После того, как задача поставлена и документация по компоненту создана, задача попадает на разработку. Текущее описание компонента также может дополняться разработчиком, особенно в разделе «Серверная часть», например, описанием новых ключевых классов. Разработчик обязательно изменяет статус компонента на «Разработка».

2. Далее задача переходит на этап тестирования. Тестировщик обязательно устанавливает статус «Тестирование» и в соответствующем поле прописывает ссылки на пройденные тест-кейсы и/или авто-тесты. Описание компонента также может дополняться тестировщиком при необходимости.

3. После релиза описанного компонента аналитик (или релиз-менеджер) устанавливает статус «Готово» и оставляет к странице комментарий следующего вида: «Готово; Задача№1, Задача№2; v.5». Комментарий состоит из трёх частей. Первая закрепляет текущий статус описания. Вторая содержит список задач, актуальных для данного описания. А третья предоставляет ссылку на текущую версию страницы (вики-система ведёт историю изменения каждой страницы). Таким образом получается, что в пятой версии данной страницы содержится описание функционала, реализованного в рамках задач Задача№1, Задача№2 и прошедшего релиз.

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

Если аналитику необходимо поставить задачу на обновление существующего функционала, то он действует схожим образом. Заводит новую задачу в таск-трекере, находит и корректирует страницу, описывающую соответствующий компонент. Обязательно устанавливает в поле статуса значение «Аналитика». В целом действия повторяются (Рис.4), но существенным является то, что в комментариях зафиксирована версия страницы, описывающая функционал компонента, который сейчас развернут в продуктивном контуре. Это очень полезно, например, для специалиста технической поддержки, которому требуется свериться с описанием, чтобы проконсультировать пользователей о том, как именно работает сейчас компонент в продуктиве. То есть ему нет нужды вникать в суть задач или уточнять у команды, какая часть описания отражает текущую работу функционала, а что только планируется к внедрению.

Если оказывается, что разработчик или тестировщик возвращаются к выполненной ранее задаче, например, чтобы исправить или проверить какой-либо мелкий баг (не требующий изменения описания компонента), а документация уже изменилась, то они также могут найти в комментариях версию страницы, соответствующую нужной задаче, и открыть её для просмотра.

Более сложным случаем является исправление бага, требующего внесения изменений в документацию (Рис.5). Тогда мы считаем, что этот баг точно «заслуживает» отдельной задачи. Аналитик должен завести такую задачу, зафиксировать текущую версию документации по компоненту в комментариях и «откатиться» на версию страницы, связанную с багом. Далее обновить содержимое страницы, не забыв добавить ссылку на новую задачу. Со временем в этот процесс втянулись разработчики с тестировщиками. При небольших изменениях они сами стали проделывать описанные выше действия.

К сожалению, на последнем этапе без аналитика обойтись не получается. Когда все или часть задач из таск-трекера по данному компоненту проходят релиз, аналитик должен провести актуализацию документации (Merge request). Он фиксирует текущую версию страницы в комментариях. Далее совмещает её с остальными версиями страницы, у которых задачи успешно завершены. Если в итоговой версии все задачи оказываются закрытыми, то в поле «Статус» устанавливается значение «Готово». Иначе статус не меняется. Если страница в статусе «Готово», а в комментариях нет задач, не отражённых в поле «Задачи», то все комментарии можно удалить.

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