06.02.2018 07:43
InfoWatch 0 285 Источник


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

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


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



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

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



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



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

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

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



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



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



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



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

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



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



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


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

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



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

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

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



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



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



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


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



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



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


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



Его плюсы:

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

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

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

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

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


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

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

Переход с MS Word


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

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


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



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


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

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



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



Затем вставляем ссылку на этот якорь в документе (Вставить -> Ссылка -> Дополнительно):

  • Для создания ссылки на другой документ перед названием якоря указываем название документа, на который нужно сослаться, затем символ «#» и после него название якоря
  • Для создания ссылки на текущий документ перед названием якоря просто указываем символ «#»



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

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


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

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

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



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

Подставьте RGB-код нужного вам цвета.

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

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

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

Комментарии (0)