Привет, Хабр! На связи старший технический писатель РТЛабс Фёдор Пеплин.
Команда РТЛабс — коллектив из 2500+ человек. Объём контента для такого количества сотрудников может исчисляться миллионами знаков, а количество пространств, используемых для хранения информации и работы с ней, — несколькими сотнями. При этом всем нам нужно хранить информацию и обмениваться ею. Один из инструментов, который мы используем для этого, — Atlassian Confluence. В этой статье я поделюсь лайфхаками и расскажу о некоторых редко используемых функциях, которые позволят значительно упростить работу с ним.
Пройдёмся от работы с самыми крупными по размеру сущностями в Confluence – Пространствами – до финального оформления внутри страниц. Представим это в форме айсберга:
Статья ориентирована на всех, кто работает с Confluence, — начинающих и опытных пользователей.
Первый уровень айсберга. Пространства
Пространства — самые крупные сущности для хранения и организации контента. Для работы с ними помогут функции поиска, добавления в избранное и выделения личных пространств.
Поиск
Функция, которая обеспечивает возможность находить нужные материалы по ключевым словам или фильтрам.
Функция Search – руководство по использованию функции поиска
Поиск — стандартная, довольно часто используемая функция. Однако когда речь идёт о большом количестве страниц, простой поиск может оказаться бесполезен из-за совпадения названий страниц или бага Confluence.
Случается, что Confluence иногда просто отказывается выполнять прямую функцию. Например, не находится статья с точно известным названием и местом расположения, но при этом у неё нет ограничений на выдачу в результатах поиска.
В этом случае используйте функцию Фильтровать по:
Если функция обычного поиска не справляется с задачей, поможет Расширенный поиск. Это режим, который позволяет строить сложные и точные запросы с помощью специальных поисковых символов, логических операторов и языка CQL (Confluence Query Language). Этот язык также может использоваться в некоторых макросах (Отчёт по свойствам страницы, Livesearch и т.д.).
Добавление в избранное
Функция добавления ссылок на пространства и страницы на панель домашней страницы.
Функция Save for later – руководство по использованию функции добавления в избранное
Добавьте пространство в избранное через специальный символ:
Добавьте страницу в избранное страницу с помощью функции В избранное:
В результате на вашей домашней странице в Confluence в меню быстрого доступа отобразятся все избранные пространства и страницы.
Личные пространства
Пространства для черновиков, личных заметок и рабочих задач, которые жёстко привязаны к конкретным учётным записям. У каждого пользователя может быть только одно личное пространство. При необходимости его не получится перенести целиком, только постранично.
Официальная документация:
Вы можете создать своё личное пространство: Значок профиля → Создать свое пространство.
Если личное пространство было создано ранее, то надпись изменится на Личное пространство и вы можете в него перейти:
Итоги исследования первого уровня айсберга Confluence: мы познакомились с фильтрами для улучшения индексации выдаваемого материала, которые позволяют кастомизировать процесс поиска информации. Добавление в избранное пространств и страниц помогает ускорить работу с наиболее активными страницами, а личное пространство позволит удобно без влияния на контент раздела проекта работать над рабочими или личными задачами.
Второй уровень айсберга. Страницы
На этом уровне вы можете управлять доступом, фиксировать статусы, ставить метки и отслеживать изменения на них.
Управление доступом к странице
Функция, которая позволяет определять, кто именно может видеть страницу или вносить в неё изменения.
Функция Page Restictions — руководство по использованию функции управления доступом
Чтобы ограничить доступ к странице, нажмите на символ замка:
Затем выберите нужный тип ограничения:
Статус Без ограничения даёт возможность редактировать содержимое всем. При любом другом статусе полный доступ по умолчанию будет только у автора.
Чтобы открыть доступ к странице и/или её редактированию, укажите пользователя в поле Введите имя пользователя или группы пользователей:
Уведомления об изменениях
Функция настройки автоматической отправки электронного письма с указанием произведённых изменений. Работает, если не отключено оповещение в блоке Сообщить об изменениях.
Официальная документация:
Нажмите Следить, если хотите получить уведомления об изменениях в разделе:
Чтобы не уведомлять пользователей, которые подписаны на изменения в разделе, отключите опцию Сообщить наблюдателям перед обновлением страницы:
Кастомизация статусов
Процесс настройки статусов страниц с помощью Comala Document, который позволяет создавать и гибко менять этапы жизненного цикла страниц в Confluence.
Примечание. Описываемый ниже процесс настройки статусов — не стандартная функция Confluence, а отдельный плагин для организации документооборота и кастомизации статусов. Начиная с версии 7.19 он называется Comala Document Management.
Официальная документация:
Чтобы перейти в настройку, откройте Инструменты для пространства → Управление документами → Управление документами (да, названия одинаковые):
Выберите опцию Page Workflow Templates, если требуются статусы для отдельных страниц. При создании Space Workflows статусы будут добавлены ко всем страницам пространства, поэтому если у вас не единообразный или не типовой контент, то проведите анализ, будет ли это уместно.
После перехода в меню добавьте новый статус или отредактируйте новую цепочку статусов через Edit:
Процесс настройки статусов удобно кастомизировать. Например, один из вариантов согласования страницы:
После сохранения добавьте на страницу цепочку статусов: откройте её и выберите Добавить рабочий процесс:
Добавить статус к определённой странице можно с помощью опции Apply only to page:
Статус отобразится на странице рядом с датой изменения, под названием.
Изменяйте статусы в режиме чтения в зависимости от выбранной схемы статусов с помощью настроенных вами же кнопок (названия кнопок смены статуса также кастомизируются):
Чтобы посмотреть историю статусов, нажмите три точки → Activity Report:
Отобразится история изменения статусов:
Особенность Confluence: чтобы избежать проблемы возможного зацикливания статусов и перегрузки сервера запросами при обновлении страниц, установлено правило — статус «прекращает» обновляться после определённого количества изменений и весь жизненный цикл документа считается завершённым, даже если статус расположен в середине жизненного цикла. Как правило, сбой может происходить через 12 смен между соседними статусами, но число может варьироваться. Если сбой произошёл, уберите статус со страницы, а затем добавьте его снова. Историю изменения статусов при этом можно сохранить – ниже расскажем каким образом.
Завершённый жизненный цикл можно удалить, нажав Удалить бизнес-процесс:
Внимание! Чтобы сохранить историю изменения статусов после удаления бизнес-процесса, оставьте при удалении пустой опцию Удалить историю действий Workflow. В этом случае при следующем добавлении статусов (рекомендуется добавлять такую же схему статусов) вся история изменений сохранится.
Метки
Ключевые слова (теги) для страниц, файлов или пространств для их группировки, категоризации и быстрого поиска контента.
Функция Add, Remove and Search for Labels – руководство по использованию меток
Метки — инструмент как для разработчиков (формирование под определённые релизы), так и для тех, кто управляет процессами, продуктами и командами, чтобы автоматизировать хаос и превратить разрозненные страницы в «живые дашборды». Они позволяют:
управлять релизами и версиями — помечайте страницы метками, затем агрегируйте весь контент релиза с помощью макроса Содержимое по метке;
собирать обратную связь и проводить исследования — ведите базу знаний по результатам встреч/интервью/опросов перед планированием бэклога или постмортемов;
агрегировать протоколы встреч — собирайте истории созвонов, затем автоматически оформляйте их в виде хронологического списка, чтобы не линковать вручную каждую встречу;
фокусироваться на важных задачах — используйте метки для страниц, которые требуют срочного изменения или согласования от команды;
архивировать без потери контекста — ставьте метку и не переживайте об агрегации архивных страниц. Таким образом, старые требования не запутают команду, но при этом их легко можно будет найти при аудите процесса;
отслеживать ретроспективу — собирайте все выводы команды в одном месте, наглядно наблюдая, решаются ли старые задачи или переносятся из спринта в спринт.
Метки располагаются в нижней правой части страницы:
Чтобы создать метку для страницы, нажмите на символ метки и введите её название:
Метку также можно поставить на изображение или любое другое вложение, например на документ в формате docx. Для этого откройте страницу, нажмите на три точки в правом верхнем углу → Вложения и поставьте любую метку к вложению на странице/пространстве:
После добавления меток используйте следующие связанные с ними макросы:
Популярные метки — список или «облако» из наиболее популярных меток;
Связанные метки — список меток, которые используются на других страницах одновременно с текущей;
Карта навигации — карта страниц, связанных указанной меткой.
Есть несколько макросов, которые помогут сделать метки инструментом для автора контента:
Отчёт по свойствам страницы — собирает данные из таблиц в макросах Свойства страницы, отбирая их по меткам;
Галерея (Gallery Macro) — собирает все рисунки с определённой меткой из всего пространства и показывает их в виде красивой визуальной сетки/галереи;
Поиск Confluence (Livesearch) — встраивает строку поиска внутрь страницы, например на главную страницу раздела. В его настройках можно указать Искать только по страницам с меткой – поиск ограничится только нужным пулом документов с меткой.
История и версии страниц
Встроенная функция Confluence, которая обеспечивает автоматическую фиксацию и сохранение изменений страницы при каждом её редактировании и публикации.
Отслеживайте жизненный цикл контента, сопоставляйте разные редакции страницы, а также администрируйте и восстанавливайте текстовые данные.
Чтобы открыть панель, нажмите три точки в правом верхнем углу → История страницы:
Появится полная история страницы с датами, авторами и версиями:
Вы можете сравнить две любые, не обязательно последовательные, версии: выберите нужные и нажмите Сравнить выбранные версии.
Вы получите страницу сравнения материала, где будет показана разница между контентом выбранных версий:
При сохранении страницы можно оставлять комментарии с описанием того, что было изменено: открыть страницу в режиме редактирования → заполнить поле Что вы изменили? → Сохранить.
Комментарий автоматически будет привязан к версии страницы. При отсутствии текста столбец Комментарий в странице истории будет пустым:
Blueprints
Готовые шаблоны страниц с преднастроенной структурой, форматированием и макросами для быстрого создания типовых документов, например протоколов встреч или ТЗ.
Blueprints — руководство по использованию инструмента
При нажатии Создать создаётся новая пустая страница без контента. Если требуется что-то шаблонное, чтобы не копировать с других страниц, используйте инструмент Blueprints. С его помощью можно создать готовую структуру страниц с любым технически доступным контентом: преднастроенными макросами, заголовками и форматированием под конкретные рабочие задачи, например для протоколов совещаний, требований к продукту или ретроспектив.
Преимущество Blueprints заключается в автоматизированности: система сама создаёт индексную страницу (список всех таких документов, например Встречи), добавляет теги и индексирует макросы, например даты, списки участников и в целом любой контент, если есть страница-источник. Благодаря Requirement Yogi или A Shared Block/Include a Shared Block данные автоматически отобразятся на странице.
Перейти в панель работы с Blueprints можно несколькими способами. Самый быстрый: нажмите три точки рядом со словом Создать → Добавить или настроить шаблоны для выбранного пространства:
Альтернативный путь: Инструменты для пространства → Инструменты контента → Page Blueprints:
После перехода в меню Blueprints нажмите Manage Page Blueprints – будет доступна панель работы с шаблонами. После этого нажмите Create blueprint.
Внимание! Чтобы шаблон отображался корректно, включите опцию Active.
Далее открывается стандартная страница редактирования — она и станет тем самым шаблоном, который будет предзаполнен перед каждым созданием страницы. Создавайте любые шаблоны, любые готовые, даже самые сложные, структуры, и сохраняйте результат.
После этого вы можете выбрать только что созданный вами предзаполненный шаблон: нажмите три точки рядом с кнопкой Создать и выберите его:
Scroll Word Exporter
Стороннее приложение от разработчика K15t, которое обеспечивает кастомизированный экспорт вики-страниц в формате docx.
В отличие от стандартной встроенной функции выгрузки Confluence, приложение позволяет гибко настраивать и сохранять стиль оформления при скачивании файла из Confluence, избавляя от необходимости вручную форматировать текст после скачивания в соответствии с редполитикой вашей компании.
Функция Scroll Word Exporter 5.17: официальное руководство
Пример выгрузки страницы до настройки Scroll Word Exporter:
После кастомизированной настройки Scroll Word Exporter:
Нажмите Инструменты для пространства → Приложения, чтобы настроить шаблоны Scroll Word Exporter:
Итоги исследования второго уровня айсберга: мы узнали, как менять доступы, включать уведомления об изменениях, кастомизировать статусы, проставлять метки к страницам и файлам и просматривать истории и версии страниц.
Третий уровень айсберга. Работа внутри страниц. Структурные макросы
Макросы в Confluence — функция платформы, которая позволяет использовать интерактивные блоки контента или данных из внешних систем, а также синхронизироваться с отчётами из Jira без использования языка разметки.
Функция Macros — руководство по использованию макросов
Внимание! «Структурные» в данной статье – эфемерная сущность, они официально не разграничиваются с другими макросами. Мы выделили их здесь сами для удобства.
Чтобы добавить макросы, нажмите + и выберите макрос из выпадающего списка, либо нажмите Выбор макроса:
Стандартное окно выбора макросов:
Единый источник информации. A Shared Block/Include a Shared Block
Макросы, которые обеспечивают отображение контента с одной страницы на другой.
Функция позволяет создать один центральный блок информации, например общую инструкцию, предупреждение или шапку документа, и транслировать его в несколько мест одновременно, исключая дублирование данных. Одна из важных особенностей: при изменении оригинального блока информация меняется на всех других страницах, где она отображается.
Инструмент не является стандартным макросом Confluence. Это стороннее расширение Include Content от компании Keysight Technologies.
Компания не поддерживает выпуск официального руководства по использованию макросов. Наиболее подробные материалы находятся на странице этого расширения в магазине приложений:
Функция Include Content Plugin — руководство по использованию макросов вложенного контента
В Confluence существует стандартный макрос Выборка, который может быть только один на страницу. Макросы A Shared Block/Include a Shared Block позволяют создавать неограниченное количество именованных блоков на одной странице и зеркально отображать каждый из них в разных местах и пространствах.
Для создания «оригинального» фрагмента, который будет транслироваться в других местах, нажмите Выбор макроса → A Shared Block:
Внутрь макроса можно добавить другие, создавая таким образом очень сложные по структуре вложенные элементы:
На другой странице, где нужно отобразить информацию из блока, добавьте макрос Include A Shared Block, в котором обозначьте страницу источника и имя блока:
В режиме редактирования макрос отображается следующим образом:
В режиме чтения будет абсолютно идентичный добавленный контент из «оригинальной» страницы.
Requirement Yogi
Приложение для Confluence/Jira, которое обеспечивает полноценное управление техническими требованиями, спецификациями и их взаимосвязями.
Функция позволяет трансформировать обычный текст Confluence в структурированную базу данных, где каждый абзац, строка таблицы или элемент списка становится отдельным атомарным требованием с уникальным идентификатором. Это избавляет системных и бизнес-аналитиков от необходимости вести учёт требований во внешних RM-системах.
Официальная документация:
Requirement Yogi Documentation – главная страница руководства
Requirement Yogi for Data Center – руководство для старых версий (Data Center/Server)
Примечание. Разработчики Requirement Yogi ведут единую онлайн-документацию для текущих версий (актуальная линейка – 4.x). Отдельного изолированного руководства под минорную сборку 3.4.17 на их сайте нет. Если вы используете версию 3.4.17, вам полностью подходит руководство для Data Center/Server, так как базовый синтаксис поиска, макросы и принципы построения матрицы трассируемости (RTM) в этих ветках совпадают.
Requirement Yogi и A Shared Block/Include a Shared Block кажутся похожими, но решают разные задачи.
Главное отличие: Include — это инструмент простого копирования контента для удобства чтения, а Requirement Yogi — инструмент баз данных для управления требованиями и их связями.
Сравнение Requirement Yogi и A Shared Bloakc/Include a Shared Block
Критерий | A Shared Block/Include A Shared Block | Requirement Yogi |
Назначение | Зеркало текста с другой страницы | Ссылка на уникальный ID требования в базе данных |
Цель | Избежать дублирования текста | Сквозная трассируемость, покрытие тестами, аналитика |
Связь с Jira | Нет. Текст внутри макросов Jira «не видит» | Прямая связь ключа требования с тикетами |
Поиск и отчёты | Обычный текстовый поиск Confluence | Сложный поиск через свой язык запросов RYQL, матрицы трассируемости |
Версионирование | Только через общую историю страницы Confluence | Поддержка версий требований, Базовых линий (Baselines) и веток (Variants) |
Работа в Confluence | Внутрь макросов можно вносить сторонние макросы, использовать различное оформление | Только строка текста или строка таблицы/списка + специализированные макросы плагин |
Пример оформления «оригинальной» страницы, откуда берётся материал/свойства контента:
Что за интересный символ (макрос RY Property) находится у поля Период, попробуйте догадаться самостоятельно ;)
В режиме просмотра на «оригинальной» странице вы можете увидеть информацию об источнике требования (на рисунке ниже курсор наведён на EXAMPLE-002). Появится всплывающее окно следующего вида:
Теперь на страницу, куда вы хотите отобразить требования/свойства, добавьте макрос RY Requirement:
В режиме просмотра вы увидите требования из начальной страницы — как из списка, так и из таблицы:
Итоги исследования третьего уровня айсберга: мы рассмотрели два набора макросов A Shared Block/Include a Shared Block и Requirement Yogi. Макросы полезны как аналитикам/РП, так и техническим писателям для трансляции единого источника контента на другие страницы.
Четвёртый уровень айсберга. Работа внутри страниц. Макросы оформления
На последнем – четвёртом – уровне находится редактирование и оформление уже созданных страниц.
Таблицы
Tables — руководство по использованию таблиц
Подробно о настройке таблиц рассказано в официальном гайде.
Мы же рассмотрим 2 редко используемых инструмента: автоматический числовой столбец и оформление первого столбца в стиле «шапки» таблицы одним нажатием:
автоматический числовой столбец – редко добавляемый инструмент, который корректно считает строки, не беря в расчёт шапку таблицы.
Часто при больших таблицах становится проблемой перемещение-удаление строк. Чтобы избежать этого, нажмите Вставить числовой столбец — Confluence добавит первым столбец с автоматической нумерацией:
выделение первого столбца таблицы стилем шапки таблицы одним нажатием. Это может потребоваться, если при оформлении предпочтительна «вертикальная» шапка.
Нажмите Выделенная колонка — оформление применится автоматически:
Разметка страницы
Функция платформы, которая позволяет разбивать стандартное вертикальное текстовое полотно на горизонтальные секции и вертикальные колонки разной ширины. Используйте это при создании дашбордов, главных страниц пространств или сложных технических отчётов.
Page Layouts, Columns, and Sections – руководство по использованию разметки страниц
Первый шаг – выбор в панели инструментов Разметка страницы:
Далее выбираем один из вариантов, например Блок с тремя колонками:
Финальный вид может выглядеть следующим образом: первый блок (таблица) состоит из одного блока, следующий — из двух, третья часть — из трёх:
Одно из главных преимуществ группирования контента — не только деление по вертикали, но и возможность «перемещать» контент выше и ниже буквально одним кликом.
Например, если вы делаете презентацию из слайдов, но не знаете, в каком точно порядке они будут размещены. Можно не копировать, достаточно нажать Поднять блок вверх, и, например, второй слайд становится первым.
Горизонтальная линия
Макрос для визуального разделения контента. Позволяет мгновенно создавать тонкую сквозную черту между абзацами, отделяя одну смысловую часть документа от другой.
Горизонтальная линия добавляется в любом месте текста страницы путём нажатия 4 символов дефиса и Enter или через добавление макроса Горизонтальная линия:
В режиме чтения горизонтальная линия будет «бесконечной» – вне зависимости от длины абзацев контента:
«Раскрыть» И «UI TABS»
Раскрыть
Макрос платформы, который является инструментом динамического скрытия и отображения контента на странице в режиме чтения.
Expand Macro – руководство по использованию макроса «Раскрыть»
Функция позволяет скрывать под сворачиваемым заголовком-ссылкой объёмные текстовые блоки, технические детали, таблицы, код или в целом делить текст по разделам на эти блоки.
В режиме чтения страницы вы можете раскрыть эту информацию в одно нажатие, что обеспечивает чистоту интерфейса и защищает документ от перегрузки лишними деталями.
Чтобы добавить макрос, нажмите Выбор макроса → Раскрыть:
До нажатия на раскрывающийся блок информация выглядит так:
После:
UI Tabs
Приложение/макросы, которые являются инструментом горизонтальной группировки и переключения контента в рамках одного экрана.
UI Tabs – руководство по использованию макросов вкладок
Выглядит как стандартные вкладки, которые вы используете, например в браузерах. Позволяет распределять большие объёмы текстовой и визуальной информации по отдельным вкладкам, нажимая на которые вы видите блок данных в режиме чтения страницы.
Использование макроса обеспечивает компактное размещение материалов на странице, исключая бесконечную вертикальную прокрутку (скроллинг) и перегрузку интерфейса. В отличие от элемента Раскрыть он переключается горизонтально, а не вертикально.
Расширение не является встроенным в Confluence по умолчанию, а является разработкой компании Refined.
Нажмите Выбор Макроса и введите UI Tabs:
В режиме редактирования добавьте сначала макрос UI Tabs, а затем внутрь него любое количество макросов UI Tab:
В режиме чтения выглядит следующим образом:
С этим макросом можно работать с Inline-комментариями — комментариями, которые можно оставлять в режиме чтения. Для этого выделите нужный текст и нажмите символ «текстового облака».
Итоги исследования четвёртого уровня айсберга: мы рассмотрели макросы оформления — «скрытые» у всех на виду функции таблиц, разделение разметки страниц, горизонтальную линию, макрос раскрывающегося блока и вкладок для оптимизации пространства на странице.
Полезные ссылки
Ссылки на официальные руководства, использованные в текущей статье:
Вместо заключения
Изучение Confluence — долгий, практически бесконечный процесс. Мы рассмотрели лишь некоторые инструменты, которые помогут сократить время на структуризацию и оформление контента как при работе с текстом отдельных страниц, так и с целыми пространствами. Постарались рассказать о функциях Confluence, которые редко упоминаются, но представляю интерес, а также о прикладных кейсах, которые находятся у всех на виду, но часто всё равно остаются невидимыми для многих пользователей.
В следующих статьях планируем рассказать о других тонкостях работы в Confluence, в том числе рассмотреть работу с разметкой в Source editor, язык CQL, приложение Scroll Word Exporter и сделать подробный обзор Инструментов для пространства. А может быть и что-то ещё ;)
Пишите ваши вопросы и пожелания в комментариях. С радостью на них отвечу!
