[Анализ и проектирование систем, Atlassian] Как мы используем Confluence для разработки требований к продукту

Автор Сообщение
news_bot ®

Стаж: 6 лет 9 месяцев
Сообщений: 27286

Создавать темы news_bot ® написал(а)
17-Фев-2021 15:36


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

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

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

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

Подробнее...

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

На странице документа с новой функциональностью:
Добавляем макрос Multiexcerpt include. В нём указываем, какой блок из какой страницы нужно вставлять:

Готовая страница фичи в режиме редактирования выглядит примерно так:


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

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

Подробнее...

SPL
На каждую страницу с требованиями к функциональным модулям добавляется метка (тэг) новой функциональности и макрос «Свойства страницы». В этот макрос добавляется стандартная таблица, в строках которой заполняются нужные свойства (на первый взгляд кажется сложно, но в документации всё подробно описано).

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


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

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

Подробнее...

SPL
На примере функционального модуля «Карточка Персоны»:
  • Находим все функциональные модули, на которые может повлиять изменения требований к карточке Персоны
  • Добавляем в них соответствующий тег (в нашем случае это #person)
  • Добавляем макрос «Результаты поиска» на странице требований к карточке Персоны


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

А читатель видит так:


Версионирование требований по релизам
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 (в русской локализации он называется «Анкер»), а затем добавить гиперссылку на него из нужной части документа.

Подробнее...

SPL
Добавляем макрос Anchor и указываем его имя (Вставить -> Другие макросы -> «Anchor»):

Так он выглядит в документе в режиме редактирования:

Затем вставляем ссылку на этот якорь в документе (Вставить -> Ссылка -> Дополнительно):
  • Для создания ссылки на другой документ перед названием якоря указываем название документа, на который нужно сослаться, затем символ «#» и после него название якоря.
  • Для создания ссылки на текущий документ перед названием якоря просто указываем символ «#».


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

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

Используйте этот код

SPL
Для заливки мы используем такой код:
<span style="background-color: rgb(202,225,255);">текст</span>

Подставьте RGB-код нужного вам цвета.
Для любителей автоматизации есть еще один лайфхак: можно сначала в визуальном редакторе изменить цвет текста, а потом в режиме редактирования исходного кода страницы с помощью регулярных выражений сделать автозамену HTML-разметки выделения текста цветом на заливку.

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

На этом всё. Задавайте вопросы в комментариях!
P.S. Статья основана на базе доклада «Лайфхаки Confluence для разработки требований» на конференции Analyst Days, видео версию этого доклада можно посмотреть по этой ссылке.
Автор статьи: Ильшат Габдуллин g1r
===========
Источник:
habr.com
===========

Похожие новости: Теги для поиска: #_analiz_i_proektirovanie_sistem (Анализ и проектирование систем), #_atlassian, #_atlassian, #_confluence, #_trebovanija (требования), #_razrabotka (разработка), #_blog_kompanii_infowatch (
Блог компании InfoWatch
)
, #_analiz_i_proektirovanie_sistem (
Анализ и проектирование систем
)
, #_atlassian
Профиль  ЛС 
Показать сообщения:     

Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы

Текущее время: 22-Ноя 19:42
Часовой пояс: UTC + 5