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



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

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


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



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

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



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



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

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

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


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


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


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



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

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



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



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


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

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



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

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

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



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



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



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


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



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



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


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



    Его плюсы:

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

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

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

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

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


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

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

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


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

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

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

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

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

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

    Автор статьи: Ильшат Габдуллин g1r
    InfoWatch
    Компания

    Похожие публикации

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

      0
      Добрый день. Спасибо за статью. Это: только по бизнес-функциональным требованиям так делаете? По технико-эксплуатационным нормам работы нового сервиса как требования собираете? Ну там, понятно — часть таких требований: выводится из нагрузочного/стресс тестирования, однако часть требований — может существовать априорно, ещё на этапе формирования бизнес-функциональных требований к сервису.
      Только — пониматься, эта часть, может, всеми сторонами проекта — по разному.
      Ну там, один считает что бизнес-операции должны приходить в систему с таким то рейтом/параллелизмом/перцентилем корректной обработки.
      Другой считает что — нет, не с таким и не совсем вот эти бизнес-операции.
      Третий — ещё что нибудь считает.

      Также собираете, сводите, согласовываете требования?
        0
        Максим, здравствуйте! Мы планируем сделать серию статей, где расскажем про наши практики работы с требованиями (тема огромная!). Про требования качества, практики выявления и согласования требований с внутренними и внешними проектными ролями — обязательно затронем! Эта статья — больше про инструмент Confluence, а не про содержательную часть работы с требованиями и проектными ролями.

        А пока могу порекомендовать посмотреть эти источники, там хорошо раскрываются эти темы:
        1. Учебник «Системноинженерное мышление» (особенно темы «Требования», «Практики проверки и приёмки» и «Принцип разделения интересов»). Картинка из учебника, для затравки:


        2. Discovering Requirements: How to Specify Products and Services
        0
        Добрый день. Не могли бы Вы в своей Базе знаний (kb.in...) оформить подобным образом хотя бы высоко уровневый RoadMap по продуктам?
          0
          Спасибо за идею, мы подумаем о публикации высокоуровневой дорожной карты, а прямо сейчас ее можно запросить у продавца, с которым вы заключали сделку.
          0
          Напомню, тут статья на хабре была, что конфлюенс в клауд переезжает.
            0
            Спасибо за информацию!
            0

            Хороших развлечений!
            А почему Confluence для работы с требованиями, а не какая-нибудь RMS ?

              0
              Хороший вопрос! Мы смотрели в сторону разных специализированных систем, но в итоге остановили выбор на Confluence по нескольким причинам:
              • Его функций нам вполне хватает, «на вырост» тоже (включая плагины и возможность кастомизировать нужные модули)
              • Это привычная для всей команды среда (Confluence используется во всех подразделениях компании + уже использовали его для других задач, например, для Базы знаний)
              • Пользуемся другими продуктами из экосистемы Atlassian: JIRA и на тот момент был Hipchat
              • У нас есть квалифицированная команда внутренней автоматизации, которая хорошо разбирается в продуктах Atlassian, то есть это сразу закрывает вопросы администрирования и кастомизации

              Про кросплатформеннность и пр — это уже само собой. И еще немного про выбор рассказывал в самом начале доклада на Analyst Days (видеозапись можно посмотреть тут: analystdays.ru/ru/talk/44960)
                0

                А планируете написать обзорную статью о просмотренных специализированных системах? Было бы очень интересно почитать.
                PS: завидую программистам — работают в прекрасных IDE, а аналитикам себе RMS на коленке приходится велосипедить…

                  0
                  У нас в ближайших планах — статьи про практики, связанные с инженерией требований (то есть содержательная часть работы СА). Но после них, возможно, снова вернемся к инструментам!
              0
              Multi Excerpt Include может сам как-то отбирать страницы и из них вставлять содержимое? Или приходится вручную добавлять на сводную страницу?
                0
                Для Multi Excerpt Include мы редактируем страницу и проставляем вручную. Но если использовать плагин «Свойства страницы», то можно на нужных страницах добавлять тег и они будут добавлять в сводную страницу автоматически.

                Тут всё сильно зависит от задачи. Если расскажете ваш кейс, попробуем под него подобрать решение)
                  0
                  Именно такой кейс я и предполагал. Перед началом работы над изменением требований я создаю сводную страницу. А все изменения в требованиях туда подтягиваются автоматически. То есть, я хочу не вручную добавлять на сводную страницу Multi Excerpt Include, а один раз его туда добавить и чтобы он сам отбирал по всем страницам пространства Multi Excerpt с определенным якорем.

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

              Самое читаемое