Как в конфлюенсе оставлять комментарии

Как комментировать статью

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

Но помимо этого в Confluence удобно вести обсуждение выложенных статей.

В Confluence есть два варианта оставить комментарий к статье. Первый — это классические комментарии, которые расположены под статьей. Второй — это комментарии на полях, как в Google Docs.

Обычные комментарии

Чтобы написать комментарий под статьей, кликните в блок «Написать комментарий…».

В нём можно упомянуть любого пользователя, для этого используйте @Имя сотрудника, чтобы он получил уведомление.

Если отвечаете на чей-то комментарий, обязательно нажимайте ссылку Ответить под этим комментарием. Тогда всё обсуждение будет выстраиваться в виде дерева комментариев и будет понятен ход обсуждения:

Обратите внимание! Когда вы создаете комментарий, вы автоматически начинаете наблюдать за статьей. И будете получать уведомления на почту обо всех изменениях и новых комментариях к статье.

Комментарии на полях

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

Такой комментарий добавляется сбоку от текста статьи. При этом на него можно ответить или отметить как Решенный.

Все решенные комментарии скрываются со страницы статьи. Их всегда можно найти в списке решенных комментариев, ссылка на который находится в меню статьи.

Как мы используем 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. На данный момент эти плагины почти полностью покрывают наши потребности.

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

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

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

Переход с MS Word

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

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

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

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

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

Подробнее.

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

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

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

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

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

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

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

Используйте этот код
Для заливки мы используем такой код:

текст

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

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

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

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

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

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

• Блог компании InfoWatch
• Анализ и проектирование систем
• Atlassian

Уровни доступа к комментариям запроса JIRA

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

Добавление, редактирование, удаление комментария

1. Откройте запрос.
2. Нажмите кнопку Комментарий в меню запроса вверху страницы.
Откроется окно комментария, где вы можете ввести свой ​​комментарий:

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

3. Введите комментарий, количество символов не ограничено.
Вы можете использовать ВИКИ разметку.
4. Если вы хотите применить ограничения на просмотр этого комментария, щелкните значок

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

Список включает в себя все проектные роли и группы, к которым Вы принадлежите. (Обратите внимание, что Все пользователи значит, что это все кто использует JIRA, а не пользователей в роли проекта) В зависимости от того, как администратор JIRA настроил Видимость комментариев в раздел Общая конфигурация, список может включать в себя группы, а также проектные роли.

5. Нажмите кнопку Добавить.

Для добавления комментариев, вы должны иметь оба разрешения:

• Просмотр проекта — для просмотра комментированных запросов
• Добавление комментариев

6. Нажмите на карандаш и редактируйте. Напротив даты появится надпись Изменен.

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

Получение постоянной ссылки на комментарий

1. Нажмите Постоянная ссылка на комментарий и скопируйте из адресной строки ссылку:

2. Если в запросе содержится много комментариев, то JIRA автоматом перейдет к этому комментарию. Комментарий просветится голубым цветом:

• Нет меток

Возможность оставлять комментарии к тексту

1. Выделите слово/строку/абзац, к которой хотите написать комментарий.
2. Через некоторое время появится значок комментария, нажмите на него.
   
3. Напишите комментарий и сохраните его.
4. Вы можете отвечать на свои комментарии и комментарии других пользователей, обсуждать вопросы.
   • Т акже, можно «Решить» комментарий, тогда комментарий будет сохранен в память страницы, но не будет отображаться.
   • Комментарии в тексте выделены едва заметно. Поэтому, лучше комментировать большие куски текста:
     

Помогите нам улучшить документацию

Чтобы помочь нам улучшить документацию, укажите имя и компанию, в которой вы работаете, а также контактные данные для связи с вами:

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

• Нет меток