16.02.18

Confluence как инструмент управления требованиями к ПО

25 мин · Обучающие

Преамбула

Некоторое время тому назад мне довелось принять участие в качестве аналитика в проекте внедрения и серьезной кастомизации одной безумной корпоративной информационной системы. Компания-подрядчик, получившая проект, не имела каких-то общих стандартов в части управления требованиями к продукту и каждая команда (как правило, состоящая из 8-12 человек) самостоятельно выбирала для своего проекта соответствующий инструментарий по управлению требованиями. Большинство коллег отдавало предпочтение старым добрым Excel + Word + SVN, кто понастырнее - использовали MediaWiki. О приобретении каких-то громоздких решений наподобие IBM Rational DOORS или SAP Solution Manager и речи не шло.

Как аналитик, я сформировал для себя следующий перечень требований к необходимому мне инструментарию:

  • Классификация и приоритизация артефактов;
  • Поддержка версионности;
  • Возможность выстраивания иерархий;
  • Возможность связывания между собой артефактов проектной документации (бизнес-требования, роли, сценарии, правила), отслеживать связанные требования;
  • Возможность связывать функциональное требование с задачами для разработчика и исходным кодом в репозитории;
  • Многопользовательский режим;
  • Связь требований с протоколами встреч, интервью, перепиской и контактами;
  • Возможность указания меток (тегов) для материалов;
  • Система должна позволять получать оперативный срез по требованиям в виде отчета, с указанием статуса и основных атрибутов (наименование, ID, бизнес-заказчик, дата регистрации и т.д.);
  • Выгрузка отмеченных материалов в общий документ (SRS, спецификацию) в форматах Word / PDF (до сих пор встречаются заказчики, желающие иметь проектную документацию "на бумаге", брр)
  • Опционально - прикрепление файлов (с возможностью предпросмотра);
  • Опционально - возможность рисовать диаграммы;
  • Стоимость системы должна быть адекватной и подходить для небольшой команды (8 человек).

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

Создаем структуру

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

Confluence Управление требованиями - структура Confluence Управление требованиями - материалы проекта

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

Бизнес-требования - раздел, содержащий высокоуровневые артефакты, выявляемые, как правило, на этапе старта проекта: бизнес-цели (финансовые и нефинансовые), риски, классификация пользователей продукта (в виде ролей), сценарии использования. Ближайший аналог этой ветки - документ о концепции или видение продукта (scope and vision). Каждое бизнес-правило, риск, роль, сценарий предпочтительно оформлять в виде отдельных страниц, каждая из которых имеет атрибуты: уникальный код, наименование, статус, дата регистрации. Все взаимозависимые артефакты должны иметь связь между собой, например: бизнес-сценарии использования должны иметь ссылки на роли, проверяемые бизнес-правила и т.д.

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

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

Структура документации почти без изменений заимствована из замечательного руководства по разработке требований к ПО: "Software Requirements" (K. Wiegers, J. Beatty). Кстати, тот же Карл Вигерс рекомендует, придерживаясь схожей структуры, заполнять её постепенно, оставляя пустые разделы на будущее. Например, заполнять раздел "Риски" по мере их выявления.

Устанавливаем связи

Еще один важнейший элемент зрелой проектной документации - связи (или ссылки) между артефактами. Функциональные требования должны иметь перекрестные ссылки (если они взаимозависимы), проверяться на соблюдение качественных требований и бизнес-правил. Также, аналитику необходимо знать, из какого рабочего материала (протокола встречи, интервью, документации) "произрастает" данное требование и иметь возможность при необходимости изучить исходный документ. Разработчику будет полезно выявить задачи по указанному требованию и исходный код, созданный/модифицированный в рамках данных задач.

Ниже приведена модель связей, используемая в нашем шаблоне проекта.

Confluence Управление требования - связи

Области Концепция, Спецификация, Материалы проекта - размещаются в Confluence. Управление задачами ранее осуществлялось в Jira (в настоящее время - в OTRS), в качестве репозитория кода используется Bitbucket (git).

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

Confluence Управление требованиями - поиск ссылок

Вы спросите: "А как же быть, если я хочу определить все входящие ссылки на бизнес-правило/требование/etc"? "Как понять, где оно используется"?

На помощь приходит плагин STAGIL Incoming Links for Confluence ( https://marketplace.atlassian.com/plugins/de.stagil.silcm.stagil-incoming-links-confluence-macro/server/overview).

После установки плагина, в нужном месте страницы вставляется одноименный макрос. Установив на связанный материал необходимые теги, можно разграничить связанные страницы по категориям, например: связанные бизнес-правила, атрибуты качества, протоколы встреч. Результат работы макроса ввыводится в виде наименований связанных страниц и ссылок на них. Есть разные стили вывода. Плагин, увы, платный. Ранее существовал бесплатный аналог (Incoming Links), не поддерживающийся в нынешней (6.5.1) версии Confluence.

В Confluence есть возможность работы "из коробки" с task-менеджером Jira. При нажатии Ctrl-Shift-J вызывается окно для вставки соответствующих задач из Jira. И наоборот - в задаче Jira указывается, на какой странице упомянута соответствующая задача. Интеграция Confluence с другими системами управления задачами (Redmine, OTRS, openproject) также не составит большого труда благодаря наличию REST API.

Confluence Управление требованиями - Jira Integration

Версионность

С этой фичей нет каких-то особых проблем. Версионность поддерживается "из коробки". Каждое сохранение страницы приводит к появлению новой версии в Истории страницы. Избыточные версии (случайное редактирование) можно удалить. В этом же разделе осуществляется сравнение версий. Редактирование утвержденных (согласованных) требований можно ограничить, запретив это всем или разрешив для определенного пользователя или групп.

Классификация, приоритизация и прочие атрибуты

Каждый артефакт должен иметь ряд классифицируемых атрибутов. Помимо возможности устанавливать метки-теги на каждую страницу, существует такой прекрасный инструмент как "Свойства страницы" (Page Properties). Воспользоваться им можно следующим образом:

  • В верхней (или любой другой) части страницы через макросы создается контейнер "Свойства страницы";
  • В этот контейнер помещается таблица с полями, содержащими в себе атрибуты требований, например: Уникальный N, Тип, Дата выявления, Аннотация, Владелец, Статус, Приоритет, Оценка, Релиз и т.д. Шапка таблицы должна содержать наименования столбцов. Конечный вариант выглядит примерно так:
Confluence Управление требованиями - Свойства страницы

Для вывода атрибутов в виде отчета (например, срез по состоянию требований), используется макрос "Отчет по свойствам страницы".

В качестве критериев отбора (фильтра) могут быть использованы:

  • Метки (например, отбираем все материалы с метками "функциональное требование", "Релиз 0.1")
  • Автор
  • Пространство
  • Упоминание о пользователе

Выводимые поля-атрибуты перечисляются в опции "Показать колонки".

Подобным образом я формирую отчетность по любым категориям проектной документации: функциональные требования, перечень участников, функциональные требования, включенные в определенный релиз. Генерация отчета, состоящего примерно из 300-350 требований выполняется за 4-5 секунд.

Диаграммы

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

  • BPMN / DMN modeler - bpmn.io, бесплатный плагин для рисования BPMN-диаграмм
  • draw.io - для рисования всего остального (контекстные диаграммы, карты и т.д.)

Экспорт документации

Благодаря относительной распространенности Confluence (в том числе как корпоративной базы знаний) и удобным механизмам выгрузки данных, проблем с передачей проектной документации практически не возникает. Заказчикам, использующим Confluence, мы экспортируем проектное пространство в формате XML, они загружают его на своей стороне. Всем прочим:

  • В формате HTML -древовидная структура, относительно удобная навигация;
  • Эспорт иерархии страниц в формате PDF.

Нажимаем ... > Открыть в иерархии (если пункт не виден - проверить полномочия пользователя) > Вкладка "Экспорт" > Выбирается формат > Пользовательский экспорт (с указанием страниц), либо Обычный. При выборе экспорта в формате PDF, результат представляет собой готовый к печати файл, с оглавлением.

Важно! Если документация ведется не на английском языке, необходимо предварительно в настройках системы (Языковая поддержка экспорта в PDF) инсталлировать поддерживающий язык шрифт (например, OpenSans). В противном случае вместо текста вы рискуете получить набор краказябр.

Отдельные страницы можно выгрузить (или наоборот - импортировать в Confluence) в формате MS Word.

Pro и contra

Стоимость. Политика ценообразования, в отличие от Jira, достаточно гибкая. Self-hosted-версия для маленьких команд (10 и менее человек) составляет 10 долларов. 25 пользователей - 1500 $, 50 - 2800 $ и так далее.

Cloud-версия - 10$ в месяц для маленьких команд, 11-100 пользователей - 5$ за пользователя в месяц.

Сэкономить, разместив Confluence как контейнер Google App Engine вряд ли получится. Confluence активно использует дисковый кэш (Lucene) и тащит за собой кучу third-party библиотек.

Системные требования. Решение написано на Java + Spring + Hibernate и весьма требовательно к вычислительным мощностям и памяти. Используемая нами конфигурация:

  • x4 Xeon E5-2620 v2 2.1GHz
  • 12 GB RAM
  • 30 GB HDD

Под базу отведен отдельный хост PostgreSQL.

Заключение

Таким образом, при надлежащем знании возможностей системы и их грамотном использовании, Atlassian Confluence представляет собой прекрасный инструмент по управлению требованиями, практически полностью покрывающей потребности аналитика средней руки. В дополнение к перечисленным выше функциям, следует отметить интуитивно понятные и дружественные пользователю возможности по форматированию и разметке текста, созданию составных страниц (макрос "Включить страницу"), прикреплению и воспроизведению изображений и аудиозаписей.

Еще одна удобная и часто используемая опция, используемая как task-лист для мелких задач, аналог Напоминаний в MacOS - это макрос "Список задач".

Confluence Управление требованиями - Список задач

Требовательные пользователи могут найти для себя дополнительную функциональность (предлагаемую бесплатно, либо за скромную сумму) в Atlassian Marketplace.