![](https://habrastorage.org/webt/_f/kg/ph/_fkgph4papyypz5l39g-ntj4cig.png)
В статье описаны наши подходы к использованию Confluence в качестве инструмента для работы с требованиями к продукту. Не претендуем на универсальность, но, возможно, эти подходы будут полезны для решения ваших задач, которые не обязательно связанны с процессами разработки требований (ведение пользовательской документации, описание внутренних регламентов работы отдела, организация базы знаний и пр).
Все изменения в требованиях к новой фиче на одной странице
Мы разрабатываем сложные Enterprise-продукты, которые тиражируются для сотен корпоративных заказчиков. В одном из наших продуктов больше ста функциональных модулей и у каждого модуля есть отдельный документ с требованиями. Фичи нового релиза, как правило, затрагивают несколько (от 3 до 20) функциональных модулей.
![](https://habrastorage.org/webt/0a/on/2-/0aon2-wani2elof54jbzcvcb4s4.png)
Чтобы понять все изменения в требованиях, проектная команда должна прочитать все документы, которые затрагивает новая функциональность, и вдобавок к этому, разобраться, что именно поменялось в каждом из них. Это долго и неудобно.
Для решения проблемы мы сделали сводный документ по каждой новой функциональности. Он содержит только изменившиеся части требований к функциональным модулям. При этом, если в исходном документе что-то изменится, это будет автоматически отражено в сводном документе.
![](https://habrastorage.org/webt/xc/o9/1a/xco91aaziusrval_jsctlb9e1au.png)
Примерно так это выглядит в жизни:
![](https://habrastorage.org/webt/lz/m3/lj/lzm3ljpcdex8qyfo79drqi2uys4.png)
Теперь проектной команде достаточно прочитать один документ, чтобы понять все изменения. Аналитик же один раз «собирает» документ и не беспокоится, что возникающие изменения нужно поддерживать сразу в двух документах.
Технически это реализовано с помощью плагина Multi Excerpt, который позволяет вставлять части одного документа в разные документы.
Подробнее...
В документе с требованиями к функциональному модулю:
Текст изменившейся части требований обрамляется макросом MultiExcerpt. Если изменение небольшое (например, поменялась какая-то одна цифра или небольшое предложение), мы добавляем в макрос немного текста вокруг этого изменения, чтобы читатель понимал контекст.
![](https://habrastorage.org/webt/n5/hn/ae/n5hnaeyfg21jltclyvqmilyurxm.png)
На странице документа с новой функциональностью:
Добавляем макрос Multiexcerpt include. В нём указываем, какой блок из какой страницы нужно вставлять:
![](https://habrastorage.org/webt/3h/ce/mu/3hcemu6dc4ds-v2mbgk6_xs6aag.png)
Готовая страница фичи в режиме редактирования выглядит примерно так:
![](https://habrastorage.org/webt/am/6n/fp/am6nfpoq0gvmxg25kxfhnsjrdb4.png)
Текст изменившейся части требований обрамляется макросом MultiExcerpt. Если изменение небольшое (например, поменялась какая-то одна цифра или небольшое предложение), мы добавляем в макрос немного текста вокруг этого изменения, чтобы читатель понимал контекст.
![](https://habrastorage.org/webt/n5/hn/ae/n5hnaeyfg21jltclyvqmilyurxm.png)
На странице документа с новой функциональностью:
Добавляем макрос Multiexcerpt include. В нём указываем, какой блок из какой страницы нужно вставлять:
![](https://habrastorage.org/webt/3h/ce/mu/3hcemu6dc4ds-v2mbgk6_xs6aag.png)
Готовая страница фичи в режиме редактирования выглядит примерно так:
![](https://habrastorage.org/webt/am/6n/fp/am6nfpoq0gvmxg25kxfhnsjrdb4.png)
Чтобы одним взглядом охватить и сразу понять статус всех требований по новой функциональности, мы добавили в сводный документ автоматически обновляемую таблицу с перечнем связанных требований, их статусами, ответственным аналитиком и кратким описанием изменений.
![](https://habrastorage.org/webt/lu/1l/by/lu1lbyry_iffvhhi4u3i2m2tzu4.png)
Делается это с помощью стандартных макросов «Отчёт о свойствах страницы» и «Свойства страницы».
Подробнее...
На каждую страницу с требованиями к функциональным модулям добавляется метка (тэг) новой функциональности и макрос «Свойства страницы». В этот макрос добавляется стандартная таблица, в строках которой заполняются нужные свойства (на первый взгляд кажется сложно, но в документации всё подробно описано).
![](https://habrastorage.org/webt/xg/8r/cc/xg8rccygytrcdmcmqmpzuzowvf4.png)
А на страницу фичи добавляется макрос «Отчет по свойствам страницы», в нем указывается метка фичи, а также список свойств, которые необходимо отображать.
![](https://habrastorage.org/webt/sx/4v/sf/sx4vsfyrgri_fp5p1h3l6v-yavw.png)
![](https://habrastorage.org/webt/xg/8r/cc/xg8rccygytrcdmcmqmpzuzowvf4.png)
А на страницу фичи добавляется макрос «Отчет по свойствам страницы», в нем указывается метка фичи, а также список свойств, которые необходимо отображать.
![](https://habrastorage.org/webt/sx/4v/sf/sx4vsfyrgri_fp5p1h3l6v-yavw.png)
«Трассировка» требований
Изменения в требованиях к одному функциональному модулю могут потребовать изменений и в других модулях. Если забыть про связанные изменения на этапе проработки требований, скорее всего, это станет известно на более позднем этапе (например, во время тестирования) и повлияет на сроки сдачи релиза. К сожалению, у нас бывали такие прецеденты.
Чтобы отследить влияние функциональных модулей друг на друга и не забывать о связанных изменениях в требованиях, мы используем функциональные возможности меток (тэгирование). Получается своего рода трассировка требований, но с крупным шагом: на уровне функциональных модулей, а не атомарных требований.
![](https://habrastorage.org/webt/eu/ua/uv/euuauvl9tsmx4rzccjju7ejnryy.png)
При более чем сотне функциональных модулей и их взаимосвязи даже такой крупный шаг трассировки позволил нам значительно сократить количество случаев, когда аналитик в процессе разработки требований к новой функциональности забывает учесть связанные требования.
Для этого мы используем стандартную функциональность меток в Confluence и макрос «Результаты поиска».
Подробнее...
На примере функционального модуля «Карточка Персоны»:
![](https://habrastorage.org/webt/pn/oy/ot/pnoyotta_epowbd3rfqd22sih5o.png)
В режиме редактирования это выглядит так:
![](https://habrastorage.org/webt/hh/rx/jx/hhrxjxbgpqqfia_s4xpnkg4bkbe.png)
А читатель видит так:
![](https://habrastorage.org/webt/yh/fa/s4/yhfas437fgker0jea-3khko4tna.png)
- Находим все функциональные модули, на которые может повлиять изменения требований к карточке Персоны
- Добавляем в них соответствующий тег (в нашем случае это #person)
- Добавляем макрос «Результаты поиска» на странице требований к карточке Персоны
![](https://habrastorage.org/webt/pn/oy/ot/pnoyotta_epowbd3rfqd22sih5o.png)
В режиме редактирования это выглядит так:
![](https://habrastorage.org/webt/hh/rx/jx/hhrxjxbgpqqfia_s4xpnkg4bkbe.png)
А читатель видит так:
![](https://habrastorage.org/webt/yh/fa/s4/yhfas437fgker0jea-3khko4tna.png)
Версионирование требований по релизам
Confluence в паре с плагином Scroll Versions позволяет для каждого нового релиза делать отдельную ветку требований, при этом у всех документов в каждом релизе остается собственная история изменений. Переключение между версиями релизов выполняется в пару кликов. Кроме того, можно сравнивать между собой требования как разных релизов, так и разных версий одного документа внутри одного релиза.
![](https://habrastorage.org/webt/-8/ko/ax/-8koaxc5gdzrso-ul_uycmbepae.png)
Так выглядит в жизни переключение между версиями релизов:
![](https://habrastorage.org/webt/1b/vp/tm/1bvptmn5mlscfpuvh6v5nxzmbew.png)
Комментирование
Для работы с комментариями мы используем плагин Talk.
![](https://habrastorage.org/webt/wj/ns/ts/wjnstsv5nktudv6jqtqplwjjhxu.png)
Его плюсы:
- Можно видеть комментарии и отвечать на них в режиме редактирования документа. Это очень удобно, когда надо вносить правки в требования по результатам ревью
- Нет проблем с параллельным комментированием (особенно если вы планируете переход с MS Word + Sharepoint: не нужно блокировать документ целиком), требования может рецензировать одновременно вся проектная команда
- Если комментарий оставляют на странице с фичей в блоке с Multi Excerpt, он автоматически появляется в исходном документе требований
Кроме этого, у него есть приятные функции, такие как выделение комментариев разными цветами, управление видимостью для разных пользователей и лайки.
От стандартного функционала комментирования в Confluence мы отказались, потому что у него были критичные для нас минусы:
- Нельзя использовать в связке с плагином Multi Excerpt
- Не видно комментариев в режиме редактирования документа
- Пропадают комментарии, если изменить текст, к которому они были привязаны
Создание диаграмм и мокапов
Сначала мы использовали MS Visio и экспортировали схемы в растровый формат, а затем загружали в Confluence. Такой подход был неудобен — актуальность схем приходится поддерживать в двух местах, для этого нужно слишком много действий.
Как оказалось, в Confluence есть множество плагинов для работы с разного рода графическими объектами (диаграммы, схемы, мокапы и пр). Balsamiq Wireframes for Confluence и Draw.io Diagrams for Confluence позволяют редактировать графические объекты, не выходя из Confluence. На данный момент эти плагины почти полностью покрывают наши потребности.
![image](https://habrastorage.org/webt/qg/94/hj/qg94hjo3w0-2wykr7bxug30750q.png)
Базовые возможности
Кратко расскажу о базовых возможностях, которые предоставляет Confluence (как и большинство других вики-систем). Чтобы не пересказывать документацию, ограничусь списком того, чем мы в основном пользуемся:
- Сравнение версий документов. Можно быстро понять, как менялась функциональность от релиза к релизу.
- Параллельное редактирование одного документа и автоматическое разрешение конфликтов. Ревью документа могут делать одновременно несколько человек и при этом не нужно ждать своей очереди, пока документ заблокирован на редактирование другим сотрудником (как было, когда мы использовали Sharepoint и требования хранились в виде Word-файлов).
- Шаблоны документов. Мы создали шаблоны по всем основным типам документов (функциональный модуль, фича, протокол совещания)
- Гибкие возможности разграничения доступа (вплоть до уровня страницы). Это удобно, например, для аутсорсных сотрудников, которым нельзя предоставлять доступ сразу ко всем требованиям
- Экспорт документов в различные форматы. Очень выручает в тех редких случаях, когда возникает необходимость передачи документов наружу.
- Интеграция с JIRA. Можно автоматически вставлять статус задач, сроки согласований и прочей информации из тикетов JIRA.
Переход с MS Word
Есть несколько неочевидных вещей, с которыми почти сразу сталкиваешься после перехода с Word на Confluence.
Нумерация заголовков
Чтобы добавить автоматическую нумерацию заголовков, нужно обрамить текст макросом Numbering headings.
![](https://habrastorage.org/webt/cj/wh/jz/cjwhjz7zywlf-j6jtw47cayrnoy.png)
Гиперссылка на раздел
Чтобы внутри документа сослаться на какую-нибудь часть документа или заголовок раздела, нужно сначала добавить макроc Anchor (в русской локализации он называется «Анкер»), а затем добавить гиперссылку на него из нужной части документа.
Подробнее...
Добавляем макрос Anchor и указываем его имя (Вставить -> Другие макросы -> «Anchor»):
![](https://habrastorage.org/webt/xc/ke/_2/xcke_23j5inmhj9i9y3lrcyfixi.png)
Так он выглядит в документе в режиме редактирования:
![](https://habrastorage.org/webt/lx/4s/h9/lx4sh97ztjajahr-kv2l1dxmz74.png)
Затем вставляем ссылку на этот якорь в документе (Вставить -> Ссылка -> Дополнительно):
![](https://habrastorage.org/webt/uz/kn/fu/uzknfu8xuoy1v8rrkpqjdpvyt20.png)
В официальной документации сказано, что ссылку на заголовок можно сделать и без макроса Ancor, но тогда ссылка будет терять работоспособность при изменении текста заголовка.
![](https://habrastorage.org/webt/xc/ke/_2/xcke_23j5inmhj9i9y3lrcyfixi.png)
Так он выглядит в документе в режиме редактирования:
![](https://habrastorage.org/webt/lx/4s/h9/lx4sh97ztjajahr-kv2l1dxmz74.png)
Затем вставляем ссылку на этот якорь в документе (Вставить -> Ссылка -> Дополнительно):
- Для создания ссылки на другой документ перед названием якоря указываем название документа, на который нужно сослаться, затем символ «#» и после него название якоря.
- Для создания ссылки на текущий документ перед названием якоря просто указываем символ «#».
![](https://habrastorage.org/webt/uz/kn/fu/uzknfu8xuoy1v8rrkpqjdpvyt20.png)
В официальной документации сказано, что ссылку на заголовок можно сделать и без макроса Ancor, но тогда ссылка будет терять работоспособность при изменении текста заголовка.
Цвет фона текста
Сделать нестандартное визуальное оформление текста, в частности выделить фон текста
заливкой, можно с помощью Markdown-разметки (Вставить -> Разметка, Markdown).
![](https://habrastorage.org/webt/1q/cz/al/1qczalnhg8-w-nsj7aw9hjblpjk.png)
Используйте этот код
Для заливки мы используем такой код:
Подставьте RGB-код нужного вам цвета.
Для любителей автоматизации есть еще один лайфхак: можно сначала в визуальном редакторе изменить цвет текста, а потом в режиме редактирования исходного кода страницы с помощью регулярных выражений сделать автозамену HTML-разметки выделения текста цветом на заливку.
<span style="background-color: rgb(202,225,255);">текст</span>
Подставьте RGB-код нужного вам цвета.
Для любителей автоматизации есть еще один лайфхак: можно сначала в визуальном редакторе изменить цвет текста, а потом в режиме редактирования исходного кода страницы с помощью регулярных выражений сделать автозамену HTML-разметки выделения текста цветом на заливку.
Это не очень удобно, но другого способа выделять текст заливкой мы пока не нашли.
Из минусов:
- Копирование и вставка из буфера обмена размеченного таким образом текста как правило ведет к потере разметки.
- Изменить разметку можно только в режиме редактирования исходного кода страницы.
На этом всё. Задавайте вопросы в комментариях!
P.S. Статья основана на базе доклада «Лайфхаки Confluence для разработки требований» на конференции Analyst Days, видео версию этого доклада можно посмотреть по этой ссылке.
Автор статьи: Ильшат Габдуллин g1r
MaksimIvanov
Добрый день. Спасибо за статью. Это: только по бизнес-функциональным требованиям так делаете? По технико-эксплуатационным нормам работы нового сервиса как требования собираете? Ну там, понятно — часть таких требований: выводится из нагрузочного/стресс тестирования, однако часть требований — может существовать априорно, ещё на этапе формирования бизнес-функциональных требований к сервису.
Только — пониматься, эта часть, может, всеми сторонами проекта — по разному.
Ну там, один считает что бизнес-операции должны приходить в систему с таким то рейтом/параллелизмом/перцентилем корректной обработки.
Другой считает что — нет, не с таким и не совсем вот эти бизнес-операции.
Третий — ещё что нибудь считает.
Также собираете, сводите, согласовываете требования?
g1r
Максим, здравствуйте! Мы планируем сделать серию статей, где расскажем про наши практики работы с требованиями (тема огромная!). Про требования качества, практики выявления и согласования требований с внутренними и внешними проектными ролями — обязательно затронем! Эта статья — больше про инструмент Confluence, а не про содержательную часть работы с требованиями и проектными ролями.
А пока могу порекомендовать посмотреть эти источники, там хорошо раскрываются эти темы: