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

Все изменения в требованиях к новой фиче на одной странице

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



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

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



Примерно так это выглядит в жизни:



Теперь проектной команде достаточно прочитать один документ, чтобы понять все изменения. Аналитик же один раз «собирает» документ и не беспокоится, что возникающие изменения нужно поддерживать сразу в двух документах.

Технически это реализовано с помощью плагина Multi Excerpt, который позволяет вставлять части одного документа в разные документы.


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



Делается это с помощью стандартных макросов «Отчёт о свойствах страницы» и «Свойства страницы».

«Трассировка» требований

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

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



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

Для этого мы используем стандартную функциональность меток в Confluence и макрос «Результаты поиска».

Версионирование требований по релизам

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



Так выглядит в жизни переключение между версиями релизов:

Комментирование

Для работы с комментариями мы используем плагин Talk.



Его плюсы:

• Можно видеть комментарии и отвечать на них в режиме редактирования документа. Это очень удобно, когда надо вносить правки в требования по результатам ревью
• Нет проблем с параллельным комментированием (особенно если вы планируете переход с MS Word + Sharepoint: не нужно блокировать документ целиком), требования может рецензировать одновременно вся проектная команда
• Если комментарий оставляют на странице с фичей в блоке с Multi Excerpt, он автоматически появляется в исходном документе требований

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

От стандартного функционала комментирования в Confluence мы отказались, потому что у него были критичные для нас минусы:

• Нельзя использовать в связке с плагином Multi Excerpt
• Не видно комментариев в режиме редактирования документа
• Пропадают комментарии, если изменить текст, к которому они были привязаны

Создание диаграмм и мокапов

Сначала мы использовали MS Visio и экспортировали схемы в растровый формат, а затем загружали в Confluence. Такой подход был неудобен — актуальность схем приходится поддерживать в двух местах, для этого нужно слишком много действий.

Как оказалось, в Confluence есть множество плагинов для работы с разного рода графическими объектами (диаграммы, схемы, мокапы и пр). Balsamiq Wireframes for Confluence и Draw.io Diagrams for Confluence позволяют редактировать графические объекты, не выходя из Confluence. На данный момент эти плагины почти полностью покрывают наши потребности.

Базовые возможности

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

• Сравнение версий документов. Можно быстро понять, как менялась функциональность от релиза к релизу.
• Параллельное редактирование одного документа и автоматическое разрешение конфликтов. Ревью документа могут делать одновременно несколько человек и при этом не нужно ждать своей очереди, пока документ заблокирован на редактирование другим сотрудником (как было, когда мы использовали Sharepoint и требования хранились в виде Word-файлов).
• Шаблоны документов. Мы создали шаблоны по всем основным типам документов (функциональный модуль, фича, протокол совещания)
• Гибкие возможности разграничения доступа (вплоть до уровня страницы). Это удобно, например, для аутсорсных сотрудников, которым нельзя предоставлять доступ сразу ко всем требованиям
• Экспорт документов в различные форматы. Очень выручает в тех редких случаях, когда возникает необходимость передачи документов наружу.
• Интеграция с JIRA. Можно автоматически вставлять статус задач, сроки согласований и прочей информации из тикетов JIRA.

Переход с MS Word

Есть несколько неочевидных вещей, с которыми почти сразу сталкиваешься после перехода с Word на Confluence.

Нумерация заголовков

Чтобы добавить автоматическую нумерацию заголовков, нужно обрамить текст макросом Numbering headings.

Гиперссылка на раздел

Чтобы внутри документа сослаться на какую-нибудь часть документа или заголовок раздела, нужно сначала добавить макроc Anchor (в русской локализации он называется «Анкер»), а затем добавить гиперссылку на него из нужной части документа.

Цвет фона текста

Сделать нестандартное визуальное оформление текста, в частности выделить фон текста
заливкой, можно с помощью Markdown-разметки (Вставить -> Разметка, Markdown).




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

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

На этом всё. Задавайте вопросы в комментариях!

P.S. Статья основана на базе доклада «Лайфхаки Confluence для разработки требований» на конференции Analyst Days, видео версию этого доклада можно посмотреть по этой ссылке.

Автор статьи: Ильшат Габдуллин g1r