Магия вне Хогвартса: 7 макросов в Confluence, которые автоматизируют и упрощают работу с документацией
Привет! Меня зовут Таня Дудо, и я уже 6 лет помогаю людям и командам обмениваться знаниями и строить рабочие процессы. Для этого использую Confluence. Да-да, ту самую wiki-систему, которую часто называют неудобной и несовременной. Сегодня выступлю ее адвокатом-обозревателем: расскажу про 7 полезных макросов для систематизации и оформления контента.
Навигация по тексту:
Часто вижу в разных компаниях, что документация в Confluence живет своей жизнью. Команды оформляют и хранят данные как хотят, никто сильно не погружается в работу этой системы. Из-за этого она кажется неповоротливой, вызывает раздражение и жаркие споры о том, какой инструмент лучше подойдет для накопления и передачи знаний.
Не буду утверждать, что Confluence — самый лучший в мире инструмент для работы с документацией. Все-таки, это дело привычки, вкуса и корпоративных ограничений. Наоборот, в тексте сосредоточусь на прикладных знаниях о том, как ласково приручить этого непростого зверя и покажу, как документация может преобразиться с использованием конкретных макросов.
Рекомендую к прочтению тем, кто:
- только присматривается к этой системе хранения данных,
- недавно начал с ней работать,
- уже использует и ищет способы сделать работу с Confluence более комфортной.
Макросы — это программные алгоритмы действий, «упакованные» в понятный графический интерфейс. Если проще, это внутренние инструменты Confluence, которые помогают делать документацию понятнее и удобнее.
Чем макросы круче текстовых редакторов?
Базовая комплектация текстового редактора выполняет простые операции по редактированию. Например, можно выделить текст жирным или курсивом, изменить цвет символов, выровнять столбцы по середине или краю.
Макросы эти возможности расширяют: интегрируют контент из внешних источников, помогают настроить навигацию внутри большой базы знаний или сформировать единый тон визуального оформления документации.
В Confluence макросов много — больше 5 тысяч , но я сосредоточусь на трех группах. Это:
- форматирование контента,
- интеграция внутреннего контента,
- интеграция внешнего контента.
Их можно называть «группами быстрого улучшения» — они помогут сделать вашу доку читабельнее всего за пару кликов.
Макросы можно добавить в статью в режиме редактирования. Они прячутся в верхней панели инструментов, за кнопкой с названием «Вставить прочий контент».
Самые популярные макросы — например, «Оглавление» и «Галерея» — лежат в выпадающем меню. Больше возможностей скрываются за строчкой «Другие макросы».
В библиотеке макросы рассортированы по группам. В левой части интерфейса можно сразу перейти к нужной группе.
Если подходящего макроса не нашлось, через кнопку «Найти еще макросы…» можно перейти в Atlassian Market и изучить платные и бесплатные дополнения, совместимые с вашей версией Confluence.
Макросы-блоки и макросы-рамки
Макрос может быть самодостаточным и не требовать вставки чего-то (например, текста, изображений или ссылок) внутри себя. В таком случае он выглядят как блок.
Если для работы макроса какой-то контент нужно поместить внутрь, он будет выглядеть как рамка.
Представьте: вам нужно спрятать под кат какой-то текст. Тогда можно использовать макрос «Раскрыть»: внутрь рамки помещаем текст, а после сохранения он окажется внутри раскрывающегося меню. В картинках ниже показываю это подробнее.
Внутрь одного макроса-рамки можно помещать сколько угодно других макросов. Главное, чтобы в пирамиде была логика. Так, например, можно сделать пирамиду из раскрывающихся пунктов или спрятать содержание статьи, если оно слишком объемное. Или добавить макрос форматирования текста.
Зачем нужны:
- делают важные текстовые вставки заметными,
- задают единый тон визуального оформления,
- позволяют вставить код в статью и подсветить синтаксис.
В работе с документацией в разных компаниях я часто замечала одну и ту же деталь: для внутренней продуктовой документации нет единых правил форматирования. В пространствах может быть отлично настроено дерево страниц, для доки созданы отдельные разделы, могут быть даже ключевые вопросы или примерный план-содержание, но внутри тексты разных статей на одну и ту же тему будут отличаться.
Пожалуй, самый распространенный пример разноформатного подхода — это выделение подсказки, предупреждения и примечания.
Наверняка вы видели, как в самом начале текста написано «ВНИМАНИЕ», а после этого идет абзац красного текста. Или подсказка отмечена звездочкой, а пояснение дано внизу страницы курсивом.
Опасность разного оформления в том, что при беглом прочтении такие акценты могут проскользнуть мимо внимания читателя. А еще к ним будет сложно вернуться и придется перечитывать текст заново.
Как использовать
В Confluence нашли изящное решение: унифицировали макросы «Подсказка», «Предупреждение», «Примечание» и «Информация».
В режиме редактирования они выглядят как макросы-рамки, внутри которых можно разместить текст.
После публикации блоки с выделенной информацией становятся заметнее, и, главное, выглядят однообразно в разных статьях.
Еще один классный макрос, который поможет сделать доку более удобной и читаемой — блок кода. Он не только форматирует текст, но и подсвечивает синтаксис языка, на котором код написан. Кроме того, подходит для размещения небольших отрывков кода внутри статьи. Например, если пишете инструкцию по созданию формы обратной связи.
Зачем нужны:
- создают «зеркало» статьи или ее отрывка в другом пространстве,
- поддерживают автообновление. Достаточно внести правки в оригинал, и все интеграции обновятся сами,
- помогают быстро перейти из «зеркала» в оригинальную статью и углубиться в нужный материал.
Бывает, что одна статья полезна для нескольких команд. Чтобы не дублировать ее в разных пространствах, можно использовать макросы «Включить выборку» и «Включить страницу».
Выборка — это небольшой отрывок из исходной статьи, а страница — полное «зеркало» всего текста.
Главный профит этого макроса в обновлении: если в исходной статье что-то поменяется, цитата или страница-зеркало изменится вместе с ней. Это намного эффективнее ручного обновления скопипащенного отрывка.
Чтобы включить цитату из одной статьи в другую, нужно:
- перейти в режим редактирования на той странице, где содержится необходимая информация,
- выделить предложение, абзац или несколько абзацев, которые надо процитировать,
- вставить макрос «Выборка».
Выделенный текст окажется внутри рамки макроса. После сохранения страница в режиме просмотра будет выглядеть так, будто ничего не произошло, но мы-то знаем, что внутри нее есть цитата.
Теперь открываем ту статью, которая будет содержать эту цитату и вставляем макрос «Включить выборку». Вуаля — цитата появилась на странице. Если исходный текст цитаты поменяется, он обновится автоматически во всех статьях, где будет включена эта выборка.
Если нужно процитировать статью целиком, то на помощь придет макрос «Включить страницу». Здесь после выбора макроса нужно ввести название статьи, которую будем транслировать на этой странице. Дополнительно включать выборку на исходной не нужно.
Save time with Easy Dropdown Menu in Confluence
In Confluence, you are able to create and edit different spaces and pages. Macros are there to give you a wider range of functionalities to edit your content.
Multiple macros can be part of a larger package, also called plugin. Plugins can be managed by your administrator.
In this article we introduce you to the Easy Dropdown Menu Plugin and show you how to reuse your predefined sets globally.
What is the Easy Dropdown Menu Plugin?
The Easy Dropdown Menu allows dropdown lists to be inserted on Confluence pages. You are able to define the dropdown values yourself. It consists of four different macros:
- Easy Dropdown Menu (Edit Mode): The values of your set can only be adjusted in edit mode
- Easy Dropdown Menu (Not Predefined): Sets can be created by yourself
- Easy Dropdown Menu (Predefined): Predefined sets can be used
- Easy Dropdown Menu (Status Macro): Predefines status can be used
However, each macro is only available on the specific page where you defined it. But what if you want to use a dropdown menu and the associated options again on other pages to save time?
In order to do this, you need to create a new predefined set.
Dropdown List
Dropdown lists should be used when you want users to pick from a list of options.
Instructions
- Create your Form using the Forms for Confluence macro.
- Add the Forms — Dropdown List macro to the form.
- Set a Name for the list.
- Set a Label for the list; this will appear next to the checkbox options.
- (Optional) Set a Description for the list.
- (Optional) Set a Null Value and Label Option. This will appear at the top of the list as a placeholder with no value. It will not be accepted if the dropdown list is set to required and an empty value is selected.
- Set a Label
- Set a Value.
- Once you have selected one option, you can choose another.
Using Empty Values with the Dropdown List
You can set options in the dropdown list that have an empty value. This can be useful when you want to force users to pick from a list and provide an empty value at the top, or it can be used to break up a list by having empty values in between sections of a list.
When using empty values, it is recommended that you set the required parameter to true, ensuring that users have to pick an item from the list.
Объединение макросов в confluence
Перед каждым аналитиком возникает выбор представления и формирования информации. Конечно, хочется выбрать более легкий способ, но не всегда этот способ соответствует ожиданиям читающего. В данной статье я поделюсь проблемами, которые были решены в рамках формирования и сопровождения реальных требований. Надеюсь, моя статья вдохновит на использование более сложных инструментов confluence.
Динамический поиск по дочерним страницам
Пространство моего проекта содержит более 800 страниц требований. При использовании стандартного поиска confluence, я столкнулся с проблемой. Дело в том, что поиск выполняется по всему пространству и требует фильтрации для более узкой выборки. Дополнительно, поиск выполняется по содержимому страниц и названиям загруженных файлов. Это не всегда удобно, особенно если необходимо искать страницы в определённой области пространства. В результате была поставлена задача реализовать поиск только по названию страниц.
Для реализации необходимо определить область поиска. У меня это был раздел требований в котором содержались страницы следующей иерархии:
Требования (родительская страница)
Создаем пустую страницу в любом месте пространства и добавляем макрос «Отображение дочерних»:
В настройках макроса указываем родительскую страницу. Это будет область нашего поиска. После сохранения на странице отобразятся все дочерние страницы каждого уровня иерархии. Кликаем правой кнопкой на странице и выбираем «Просмотр кода страницы». В коде страницы нам необходимо найти и скопировать все ссылки дочерних страниц в html. Так как на странице много кода, можно воспользоваться поиском по названию одной из страниц. Ссылки на странице размещены одной строкой и содержат лишние теги. С помощью инструментов форматирования html (для массового удаления лишних тегов используем word), код необходимо привести к виду:
Вторым шагом создаем страницу, где будет размещаться наш поиск. На страницу добавляем макрос-рамку «HTML»:
Данный макрос выполнит код html, который мы разместим в рамку. В зависимости от ваших потребностей, вы можете разместить любые вспомогательные html-элементы на форме. Реализуем следующим образом:
1) Разместим два раскрывающихся списка (при выборе значения списка, текст подставляется в строку поиска):
2) Разместим поле для поиска и кнопку «очистить»:
3) Далее добавим ссылки из первого шага:
4) Добавляем скрипты для раскрывающихся списков, поиска и кнопки «очистить»:
5) Сохраняем страницу и пользуемся.
6*) Для более эстетичного отображения страницы, можно разместить макрос html в рамке макроса Aura Panel.
В результате мы реализовали возможность выполнять динамический поиск по заданной области пространства. Я не сомневаюсь, что разработчики и тестировщики оценят такую фичу и будут чаще читать ваши максимально «понятные» требования. Минус данного подхода: при добавлении новых страниц потребуется обновление набора ссылок. Но это займет всего 10 минут вашего времени.
Многоуровневые формы
Часто аналитику требуется объединять большие объёмы сложно читаемых данных. Для этого Сonfluence предоставляет большой набор макросов. Например, с помощью макросов Aura-Tab и Aura-Tab Group можно создать объект с табами. Макросы обладают гибкими настройками, но проблема заключается в одном уровне вложенности создаваемых форм. В результате была поставлена задача реализовать многоуровневую вложенность с помощью объединения макросов.
Давайте разберемся, как работают макросы Aura-Tab и Aura-Tab Group. Нам необходимо разместить макрос Aura-Tab Group, в котором будут размещены макросы Aura-Tab. Каждый Aura-Tab представляет собой таб для переключения между контентом, который вы разместите в рамку макроса. После сохранения мы получим одноуровневые формы с контентом.
Для добавления второго уровня вложенности нам потребуются макросы UI Tab и UI Tabs. Принцип работы макросов такой же, как у Aura.
Разместим макрос UI Tabs в рамке макроса Aura-Tab. В рамке UI Tabs разместим нужное количество табов UI Tab. Сохраняем и пользуемся.
С помощью объединения группы макросов нам удалось реализовать двухуровневый список табов. Данный способ отлично подходит для описания сложных объектов.
Динамическое объединение таблиц
В работе с требованиями, аналитики используют различные способы представления информации. Одним из популярных и доступных способов является табличное представление. Понимая данный факт, confluence предоставляет большой набор инструментов для работы с таблицами. В этот раз мы решим проблему динамического объединения таблиц. Наша задача создать таблицу, которая будет объединять несколько таблиц и предоставлять актуальные данные.
Допустим, у нас есть две таблицы, которые заполняются разными людьми из разных источников данных.
Для использования таблицы, нам необходимо разместить каждую таблицу в рамке макроса «Выборка таблицы». В настройках макроса нужно задать уникальное имя выборки.
Далее создаем страницу и добавляем макрос объединения таблиц Table Transformer.
Выбираем один из трех способов объединения, в нашем случае будет Lookup tables. Нажимаем кнопку вставить.
В рамку макроса размещаем два макроса «Вставка выборки из таблицы». В настройках выборки ссылаемся на уникальное имя, которые мы указывали в макросе «Выборка из таблицы».
В рамку макроса размещаем два макроса «Вставка выборки из таблицы». В настройках выборки, ссылаемся на уникальное имя которые мы указывали в макросе «Выборка из таблицы».Возвращаемся в настройки макроса Table Transformer. И видим, что макрос самостоятельно определил ключ объединения таблиц (Паспорт).
Результат после сохранения страницы:
Таким образом, при изменении данных в исходных таблицах, данные в объединенной таблице будут обновляться. Для объединенной таблицы доступны стандартные функции фильтрации. В зависимости от потребностей, доступно кастомное объединение. Например, можно прописать SELECT * FROM T1 OUTER JOIN T2 ON T1.’Паспорт’ = T2.’Паспорт’ и получить такой же результат. T1 и T2 это соответственно первая и вторая таблица в рамке макроса. Отличная фича для экономии времени при работе с таблицами, главное не показывать свои «кастомные селекты» разработчикам sql.
Заключение
В данной статье описана лишь часть «необычных» объединений макросов. Не стоит забывать о гибкости и возможностях confluence. Попробуйте создать что-то новое в своей песочнице. Надеюсь данная статья поможет в написании реальных требований.