Многие так или иначе сталкивались с продуктами компании Atlassian, такими как Confluence, Jira. Их использование позволяет организовать работу команды разработки наиболее удобным способом, обеспечить доступ к информации проекта. Кроме того, что эти продукты обеспечивают онлайн-доступ к основным материалам проекта, они также включают в себя много интересных плюшек. В этой статье ведущий системный аналитик ДОМ.РФ Екатерина Шипкова расскажет о полезных фичах Confluence.
Одним из основных инструментов аналитика в IT является Confluence или Wiki. Данные пространства используются для написания требований к разрабатываемой системе и в целом похожи друг на друга своими функционалами. Требования, которые аналитик формирует к системе, должны отвечать определенным критериям, таким как: полнота, завершенность, атомарность, непротиворечивость, идентифицируемость, трассируемость. Поддерживать эти критерии становится крайне непросто, если документация проекта включает множество страниц со статьями, т.к. время, которое автор будет затрачивать на то, чтобы скорректировать одинаковые требования, найти их в пространстве проекта будет колоссальным. Именно для сокращения времени на поиск необходимой информации и сокращение дублирования одинаковых материалов можно использовать различные макросы в Confluence.
Что такое макрос в целом?
Макрос в Confluence - это инструмент, который помогает красиво структурировать и эффективно агрегировать информацию в системе, что приводи к снижению трудозатрат на оформление данных стандартными способами форматирования. И в целом “красота” служит для более наглядного отображении информации.
Почему стоит использовать макросы?
Ускорение работы. Изучение работы с макросом один раз может в дальнейшем очень сильно сократить время, которое мы бы потратили на написание документации без использования макросов. Также само использование макросов позволяет расположить информацию максимально доступно для дальнейшего использования.
Визуальная доступность информации. Использование макросов позволяет визуально оформить документацию таким образом, чтобы она была понятна всем. Ограниченный выбор для визуализации также помогает поддерживать документацию в едином стиле.
Не нужно использовать стороннее ПО для решения рабочих задач, тратить время на поиски необходимых инструментов. Например, если необходимо построить какие-то графики, диаграммы и т.д., не нужно искать дополнительные средства - большинство задач можно решить с встроенными инструментами.
Кто может использовать макросы в своей работе
Т.к. макросы достаточно разнообразны, то использовать их в своей работе могут не только аналитики, но также и другие участники команды:
Архитекторы
Project manager
Product Owner
Технические писатели
QA
Сотрудники сопровождения
Разработчики
Тематическое разделение макросов
Часть наиболее используемых макросов в Confluence вынесена в панель быстрого доступа, что позволяет достаточно быстро получить доступ к необходимым инструментам.
Если в быстром доступе нужный макрос не найден, то можно использовать расширенный список макросов.
Расширенный список позволяет искать необходимый макрос (если известно его точное или примерное название).
В случае, если на текущий момент конкретный макрос неизвестен (не знаем о его существовании и просто изучаем/знаем, что макрос есть, но не помним конкретное название), то в этом случае в Confluence есть тематическое разделение макросов, которое позволяет нам существенно сократить время на поиск нужного инструмента. Само разделение на категории также позволяет примерно понять, в каком именно разделе нам необходимо искать макрос.
Стоит отметить, что есть множество похожих макросов по своей функциональности, однако они отличаются визуально.
Макросы “Внешний контент”
JIRA
Макрос, который позволит визуализировать всю необходимую информацию из JIRA. Он может появляться автоматически, например, когда вы вставляете ссылку на задачу из JIRA - тогда ссылка автоматически преобразуется в макрос. Кроме банального отображения краткой информации по задаче и связи статьи в Confluence и задачи в JIRA, данный макрос можно использовать для отображения информации по отфильтрованным задачам. Для этого в поисковой строке макроса необходимо прописать запрос для фильтрации. Запрос можно либо скопировать из JIRA, переключив базовый поисковый режим на продвинутый, либо написать самостоятельно.
Также можно выбрать, какие поля и сколько запросов будет отображаться при визуализации фильтра в режиме чтения. Визуальное отображение макроса представлено на ниже:
одна задача
фильтр задач
Swagger
Макрос, который визуализирует API, описанное в вашем Swagger. Есть несколько способов работы с данным инструментом:
самостоятельно сформировать YAML-описание Swagger и добавить его в макрос;
с помощью ссылок и доступов настроить связь Confluence и действующего сваггера.
Использование макроса HTML Include позволяет визуально отобразить веб-страницу, на которую ведет указанная в макросе ссылка. При визуализации данной страницы работа с ней внутри Confluence происходит аналогичным образом, как если бы страница была открыта вне Confluence.
Стоит отметить, что отобразить таким образом в Confluence можно не любой ресурс, а только из допустимых для вашего пространства списка адресов.
Коннектор виджета добавит в вашу документацию контент с других ресурсов, для просмотра которого не нужно будет переходить непосредственно на ресурс. Настройки макроса позволяют не только указать адрес, откуда отображать видео, но и настроить размеры отображения.
Макросы “Медиа”
Макросы, относящиеся к разделу “Медиа”, такие как Office Excel, Office PowerPoint, Office Word, PDF, также могут добавляться в Confluence автоматически, например, когда в статью добавляется файл с соответствующим расширением. Кроме автоматического добавления их можно добавить вручную, при этом настроив критерии отображения информации для миниатюр.
В режиме просмотра данные макросы позволяют открыть документы в Confluence без дополнительного скачивания файла на ПК.
Макросы “Навигация”
Макросы навигации в основном направлены на то, чтобы организовать доступность необходимой информации в Confluence максимально удобным образом. Чаще всего к таким макросам относятся макросы содержаний, например, Page Tree, Page Tree Search, UI Children, UI Children Cards, Оглавление, Оглавление пространства, Отображение дочерних. При корректной настройке все вышеперечисленные макросы взаимозаменяемы, однако стоит отметить, что некоторые макросы (UI Children, UI Children Cards) не допускают отображение иерархии глубже первого уровня.
Якорь
Данный макрос используется, чтобы обозначить определенные места статьи, на которые в дальнейшем необходимо будет ссылаться. Визуально сам Якорь на странице в режиме просмотра никак не отображается, он виден только в режиме редактирования. Якорь работает только вместе с макросом “Ссылка”. “Якорей” на странице может быть много.
Также навигацию по статьям Confluence можно настроить с помощью “Ссылки”. Ссылка может появляться автоматически. Например, когда добавляется ссылка на страницу в Confluence, то она автоматически заменяется на название нужной страницы. Также Ссылку можно вставить самостоятельно с предварительными настройками.
“Поиск” осуществляется либо по всему пространству Confluence компании, либо ограничевается пространством проекта. При вводе названия страницы вам будут предложены страницы, отвечающие критериям поиска;
Раздел настроек “Часто просматриваемые” позволяет выбрать нужную страницу из часто посещаемых страниц, чтобы не нужно было искать по наименованию;
Для отображения ссылки на файл используется раздел настроек “Файлы”. При выборе файла для ссылки можно выбрать любой документ, который уже был загружен на страницу;
“Web-ссылка” - это именно тот раздел, который включается автоматически, когда мы вставляем url-адрес в текст статьи, но также мы можем настроить его вручную, например, указать другое название для ссылки;
“Дополнительно” - раздел, который может работать так же, как и “Web-ссылка”, но есть одно отличие: с помощью этого раздела и использования макроса Якорь можно получить ссылку на определенное место страницы в Confluence. Для того чтобы использовать ссылку на якорь, на текущей странице необходимо в строке “Ссылка” прописать следующее: “#якорь”, где “якорь” - название заданного якоря. Для того чтобы ссылка вела на якорь на другой странице в Confluence, ссылку необходимо оформить следующим образом: “Название страницы в Confluence#якорь”. Название страницы должно полностью совпадать с названием страницы в пространстве Confluence.
После того, как данная ссылка будет настроена, появляется возможность переходить на страницу “Разметка страницы” в раздел статьи, где поставлен якорь.
При любом способе настройки макроса “Ссылка” всегда можно настроить текст ссылки, который будет отображаться в тексте статьи.
Макросы “Содержимое Confluence”
Макросы Ссылка и Якорь позволяют избежать дублирования информации при написании статей в Confluence. Единственный минус данных способов: при переходе по ссылке приходится перемещаться с текущей статьи на страницу, куда ведет ссылка. Стоит отметить, что в Confluence есть макросы, которые позволяют визуализировать информацию в режиме просмотра на текущей странице, при этом избегая дублирования ввода информации на нескольких страницах в режиме редактирования.
К таким макросам относятся следующие:
Включить страницу. При использовании макроса на текущую страницу вставляется полностью указанная страница.
Включить выборку. Данный макрос используется вместе с макросом Выборка. Чтобы на текущей странице отобразить часть статьи с другой страницы, необходимо на странице №2 добавить выборку, которая будет содержать текст, необходимый для отображения и на странице №2, и на текущей странице. После этого на текущей странице используется макрос Выключить выборку, при его настройке указывается название страницы №2. К минусам данного способа относится то, что “Выборка” на странице может быть только одна, т.е. если одна статья содержит несколько блоков информации, которую необходимо отобразить в других требованиях, то макросы, связанные с выборкой, не подойдут.
Include A Shared Block, как и выборка - парный макрос. Используется в паре с A Shared Block. Работа с данными макросами аналогична работе с макросами, связанными с выборкой. Отличием является лишь то, что на одной странице может быть неограниченное количество A Shared Block, которые затем будут отображены на разных страницах посредством Include A Shared Block.
Макросы “Схемы и изображения”
Макросы данного раздела предназначены для визуализации информации без использования дополнительных инструментов, не входящих в Confluence.
PlantUML Macro, PlantUML Render Macro, PlantUML Diagrams for Confluence - макросы, предназначенные для визуализации UML-диаграмм в Confluence. Отличительной чертой PlantUML Diagrams for Confluence является то, что посмотреть описанную диаграмму можно сразу в макросе, не включая предварительный просмотр и не выходя из режима редактирования страницы, чего нельзя сделать при использовании PlantUML Macro или PlantUML Render Macro.
PlantUML Diagrams for Confluence в режиме редактирования:
PlantUML Macro в режиме редактирования:
PlantUML Macro, PlantUML Render Macro, PlantUML Diagrams for Confluence в режиме просмотра:
Также в Confluence есть встроенный макрос, позволяющий работать с BPMN-диаграммами: BPMN Modeler. Кроме возможности работы с BPMN-диаграммами данный макрос позволяет сохранять готовые диаграммы на рабочую станцию и открывать .xml, .bpmn-файлы с диаграммами BPMN с ПК.
Roadmap Планировщик позволяет визуализировать дорожную карту проекта:
Gliffy объединяет в себе множество различных вариантов по работе с разными схемами и диаграммами. Данный макрос позволяет не только работать с BPMN, UML, Roadmap, его также можно использовать для изображения схем сетей, построения SWOT-анализа и т.д. По набору возможностей, реализованных в данном макросе, можно провести аналогию с MS Visio, который уже встроен в Confluence.
Макросы “Форматирование”
На изображении ниже представлены 5 макросов. В столбце справа находятся такие макросы как Предупреждение, Примечание, Подсказка, Информация. Левый столбец содержит в себе лишь один макрос UI Text Box, но с разными настройками. Как можно видеть, визуально данные макросы похожи, и вместо поиска четырех разных макросов можно использовать один, который будет изменяться исправлением всего лишь одной настройки.
Макросы UI Expand и Раскрыть тоже выполняют идентичные функции: сокрытие информации в статье для уменьшения ее размеров. Например, в такие макросы можно скрыть какие-то дополнительные пояснения, более детальные описания алгоритмов и т.д., данные, которые необходимо увидеть не каждому, кто будет знакомиться с требованиями, а только определенным лицам.
Макрос UI Expand позволяет скрыть текст в статье. При необходимости макрос можно настроить таким образом, что по умолчанию он будет раскрыт всегда. Для этого при настройке макроса необходимо установить чек-бокс "Expanded".
Макрос Раскрыть позволяет скрыть текст в статье, однако не имеет дополнительных настроек и позволяет лишь определить текст, который будет отображаться в статье.
Блок кода позволяет отобразить в статье необходимый код. При настройке макроса можно выбрать подсветку синтаксиса (YAML, SQL, Java, Groovy и т.д), а также настроить тему отображения, указать название блока кода и добавить возможность отображения блока в свернутом виде.
Эпилог
В данной статье рассмотрены не все макросы, которые находятся в Confluence, а часть наиболее используемых в работе макросов. При желании и необходимости можно ознакомиться со всеми макросами, доступными в Confluence, более подробно узнать об их работе. Каждый макрос содержит в себе краткое описание своей функции и ссылку на инструкцию по работе с ним.
