Привет, Хабр! Я Ульяна, старший аналитик в направлении продуктового и системного анализа в отделе Tinkoff Mobile Core. Наш отдел разрабатывает общие технические решения — библиотеки, которые используются в мобильных приложениях экосистемы Тинькофф.
Для наших коллег мы проектируем документацию и инструкции для разрабатываемых библиотек, различных общих проектов и исследований. Вот главные требования к документации: она должна быть максимально понятной и структурированной, а поиск — легким и быстрым.
Документацию мы ведем в Confluence — и обычно, когда я рассказываю про Confluence, у многих он вызывает, мягко говоря, неприятные ассоциации. Миллион разделов, неудобная навигация, портянки бесконечного текста и многое другое, что отбивает желание даже открывать любую wiki. Но я спешу вас обрадовать — все может быть совсем иначе!
Расскажу, как выжать максимум из Confluence, чтобы вы могли научиться использовать макросы и другие его возможности и с помощью них быстро проектировать понятную и удобную документацию.
Что такое Confluence и зачем он нужен
Confluence — это инструмент, предоставляющий функциональность для создания командных пространств, в котором хранятся все накопленные знания. Эти знания объединены с возможностями для совместной работы.
Confluence используют для:
Ведения и хранения проектной документации и рабочих материалов.
Структурирования всей информации в едином месте.
Совместной командной работы в режиме реального времени.
Оптимизации командных и проектных процессов.
Основные инструменты для работы в Confluence — макросы, разметка, метки и шаблоны.
Макросы — один из основных инструментов в Confluence. Макросы — это БА-А-АЗА!
Макросы позволяют делать таблицы, уведомления, оформление текста, вкладки и еще много-много всего.
Дисклеймер!
Важно знать и помнить:
Не все макросы доступны из коробки и бесплатны. Будьте готовы к тому, что какие-то из перечисленных макросов могут отсутствовать или, наоборот, не описаны в этом списке, потому что отсутствуют у меня 🙂
Не используйте все макросы сразу: они увеличивают время загрузки страниц и могут привести к утилизации ресурсов сервиса в целом — даже до полной недоступности.
Основные инструменты для редактирования wiki-страниц вынесены на верхнюю панель, а макросы прячутся под плюсом:
Макросы открывают возможность подавать информацию понятно и делятся на типы: форматирование, схемы и изображения, макросы внутреннего контента, макросы внешнего контента, навигация, отчеты и с использованием CSS.
Как настроить макросы форматирования
Макросы форматирования помогают визуально выделить текст и показать его важность, скрыть громоздкие элементы и вставить код в документацию с выделением синтаксиса.
«Информация», «Подсказка», «Примечание» и «Предупреждение» — макросы представляют собой макрос-рамку, нужно просто поместить информацию внутрь. При сохранении или в режиме предпросмотра появится подсветка текста.
«Блок кода» — вид макроса форматирования, при котором можно вставить код в рамку и задать нужные параметры: подсветка синтаксиса, скрываемость блока, нумерация строк кода и тема. Примеры блока в двух темах:
Макрос «Раскрыть» помогает скрыть громоздкую информацию на странице, например, если нужно добавить крупную схему или таблицу, дополнительную информацию или какую-то предысторию.
Макрос «Панель» отображает текст в рамках настраиваемой панели. Можно выбрать стиль и цвет рамки, цвет фона, текста и заголовка с помощью HEX-кода.
С помощью макроса Highlight можно выделить конкретную часть текста, абзаца, как в ежедневнике маркером. Цвет выделения выбираете самостоятельно.
Макрос Round Rectangle — графический закругленный прямоугольник, который можно настроить: задать заголовок, установить нижний колонтитул, цвет и размеры.
Макрос Alert поможет настроить всплывающее уведомление на вашей странице в Confluence. Например, если документация еще в работе, чтобы пользователи при входе на страницу сразу увидели предупреждающую информацию.
Alert можно настроить несколько видов в зависимости от контекста — Success, Info, Warning, Error. Примеры отображения при сохранении всех видов:
Button Hyperlink и Button Group — макросы, которые помогают создавать кнопки с гиперссылками и собирать их в связанные группы. Можно сделать кнопку как на внутренний контент, так и на внешний, а еще настроить наименование, тип и иконку кнопки, ссылку на которую поведет при тапе на кнопку.
Section и Column — макросы для оформления текста с помощью столбцов, объединенных в секцию. Столбцов может быть любое количество и разных размеров. Главное — помнить, что столбцам нужно влезть на страницу, в ином случае это будет похоже на час-пик на станции метро «Выхино».
Horizontal Navigation Bar, Horizontal Page, Tabs Container Tabs и Page — макросы для создания горизонтальных и вертикальных вкладок. Аккуратнее с этим макросом при оформлении важной информации: при поиске на странице можно ее не найти, если не находитесь на конкретной открытой вкладке.
Как настроить макросы схем и изображений
Схемы и изображения помогают построить диаграммы и графики, вставить изображения или построить роадмап.
PlantUML Macro — для UML-схем в документации, написанных на PlantUML. В макросе нужно вставлять схему кодом, и если кто-то из команды захочет его поправить, нужно будет просто внести правки в код.
Диаграмма Gliffy — встроенный редактор для моделирования процессов, тоже удобен для командной работы. Хотя, признаюсь честно, мое сердечко отдано UML.
Spacegraph — макрос-блок, который помогает выполнять сложные операции в Confluence. Он отображает структуру пространства или раздела в виде схемы. Можно настроить в конкретном пространстве, указать ограничения количества блоков, изменить цвет оформления и размер.
Мы часто используем этот макрос на странице с вводной информацией, чтобы помочь пользователю сориентироваться в документации.
«График» —в Confluence можно строить различные графики по данным со страницы под конкретную потребность. Настраиваются тип графика, ориентация экрана, размеры, наименование, подзаголовок, название осей, цвета, диапазон минимальных и максимальных значений и еще много различных параметров, чтобы сделать график уникальным для вас.
«Roadmap Планировщик» — название говорит само за себя. Можно построить Roadmap для проекта с помощью макроса. На мой взгляд, этот макрос слишком простенький для крупных проектов, поэтому я бы рекомендовала использовать другие инструменты для Roadmap.
Как настроить макросы внутреннего контента
Макросы внутреннего контента помогают настраивать организацию данных, строить аналитику по внутренним данным из wiki-пространств, создавать опросы и голосования, переиспользовать контент в разных частях документации.
«Фильтр таблиц» помогает организовать табличные данные: навесить фильтры и сортировку. Нужно вставить таблицу в рамку и выставить нужные настройки.
«Выборка таблицы», «Вставка выборки таблицы» и «Диаграмма из таблицы» — макросы, которые позволяют использовать копию таблицы для построения сводных таблиц и графиков на основании одних и тех же табличных данных. Правки вносят в одно место, а они автоматически подгружаются везде.
Как настроить выборку и вставку таблицы:
Добавить макрос «выборка таблицы».
Задать уникальное наименование для выборки и вставить в рамку таблицу с данными.
Использовать макрос вставки выборки таблицы, чтобы вставить копию этой выборки.
Указать в макросе вставки уникальное наименование, придуманное для выборки таблицы, чтобы данные из нее отобразились во вставке.
Макрос «Диаграмма из таблицы» используется для создания динамических диаграмм из данных таблиц, которые мы можем указать явно таблицей в рамке или подтянуть с помощью макроса вставки. Пример переиспользования данных из созданной выборки таблицы:
Forms — Confluence позволяет делать различные формы с опросами и голосованиями. Все данные из форм можно отправить на электронную почту.
Нужно вставить макрос Forms, а в него все, что идет с приставкой Forms.
Multiexcerpt и Multiexcerpt include — макросы для свободного ввода.
Как настроить:
Добавить макрос multiexcerpt.
Задать уникальное наименование и вставить данные.
Вставить копию этой выборки, используя макрос multiexcerpt include (при необходимости).
Указать в макросе вставки уникальное имя, придуманное для выборки, чтобы данные из нее отобразились.
«Отчет по задачам» — макрос помогает создать отчет из определенных источников, людей, статусов. Мы в команде часто используем его для retro, 3Amigo и MN, чтобы не терять зафиксированные todoшки.
«Отчет о содержимом» — макрос генерирует отчет о содержимом в формате таблицы на основе проставленных на страницах пространства меток. Мы этот макрос используем для организации прогресса RFC и RND.
Как настроить макросы внешнего контента
Макросы внешнего контента помогают настроить связь с Jira, отобразить данные из Figma, Miro и иных источников, построить различные отчеты и аналитику по связанному внешнему контенту.
Jira — макрос встраивает задачу или фильтр из Jira.
Structure.Gantt — макрос для отображения диаграммы Ганта в Confluence, если вы используете Jira Structure. Нужно только указать идентификатор вашей структуры. Можно выводить какую-то конкретную часть из Structure, настроить период автоматического обновления или оформление диаграммы.
«Время решения» — макрос отображает гистограмму времени, затраченного на решение запросов по проекту или фильтру из Jira.
«Гаджет состояния спринта» поможет визуализировать состояние и прогресс вашего спринта.
«Запросов в работе» — макрос покажет все задачи в работе в зависимости от заданных настроек. Данные отображаются для конкретных currentUser.
«Виджет коннектора» — макрос отображает внешний контент, нужно только указать ссылку.
Как настроить макросы навигации
Макросы навигации помогают структурировать информацию, организовывать кросс-навигацию между страницами и сделать поиск информации быстрым и удобным.
Livesearch помогает встроить поле поиска на страницу Confluence. В поле по мере набора текста будут отображаться результаты поиска.
«Отображение дочерних» — макрос отображает все дочерние страницы к той странице, где он используется, или от указанного конкретного раздела и страницы. Я стараюсь его применять на верхнеуровневых страницах, чтобы настроить удобную навигацию и вложенность страниц.
«Оглавление» — макрос создает оглавление текущей страницы на основании заголовков страницы
Page Tree — макрос отображает дерево страниц. Можно настроить страницу, для которой нужно отобразить дерево, ограничения, сортировку и добавление строки поиска.
«Якорь» — макрос позволяет создать якори внутри страницы, которые могут быть гиперссылкой.
Как настроить:
Вставьте макрос «Якорь» в месте, на которое хотите ссылаться, и придумайте имя.
Нажмите «Вставить ссылку» в верхней панели, чтобы сослаться на якорь.
Укажите имя якоря через #, если нужна ссылка на якорь в рамках той же страницы.
Укажите имя страницы и якоря через # в блоке «Ссылка», чтобы дать ссылку на якорь другой страницы в том же пространстве.
Укажите в блоке «Ссылка» ключ другого пространства, через двоеточие название страницы и якоря через #, чтобы дать ссылку на страницу из другого пространства. Например: MobileCore: Календарь отпусков#Мой якорь.
Укажите в блоке «Ссылка» ссылку на страницу, добавив синтаксис #:~:text= и конкретное слово или фразу, чтобы дать ссылку на конкретное слово или фразу. Например: https://wiki.ru/pages/viewpage.action?pageId=250575000#:~:text=Как настроить.
Как настроить макросы-отчеты
Макросы-отчеты помогают создать различные календари, построить отчеты по свойствам страниц, импортировать данные и преобразовать в отчет.
Большую часть макросов мы разобрали в рамках других типов, потому что макросы могут быть в нескольких типах одновременно. В этом разделе разберем всего один вид макросов.
«Свойства страницы» и «Отчет по свойствам страниц». В макрос «Свойства страницы» можно поместить что угодно, а сам макрос скрыть — и контент будет виден только в режиме редактирования.
По данным из макроса «Свойства страницы» можно делать «Отчет по свойствам страницы». Этот макрос соберет всю информацию о свойствах конкретных страниц и выведет в виде таблицы.
Как настроить макросы с использованием CSS
Чтобы построить ракету в вашей документации, используйте стиль CSS. Это более продвинутый уровень, а если вам не хочется сильно заморачиваться, можно соорудить ракету попроще из макросов, которые мы обсуждали ранее.
Какие макросы используют CSS:
Div — блочный элемент. Нужен, чтобы выделить фрагмент в документе, который вы хотите изменить. Чтобы обратиться к нему, укажите атрибут class или ID с именем селектора.
CSS Stylesheet — создан, чтобы писать CSS-стиль и обращаться к созданным классам.
Clickable — помогает создать кликабельные блоки.
Создадим кликабельный блок с заголовком и картинкой для примера:
Создайте макрос с классом test-component-panel. В макросе можно задать наименование, стиль и язык кода, но мы ограничимся дефолтными настройками.
Добавьте внутри класса новый макрос Clickable, чтобы зона наших настроек была кликабельна. В нем укажите ссылку для перехода на нужную страницу.
Добавьте новые классы: например, с настройками размера, цвета, отступов или со вставкой картинки.
Вставьте макрос CSS Stylesheet, чтобы наша ракета взлетела. В CSS Stylesheet добавьте CSS-стиль, и данные из кода будут обращаться к нашим классам и заполнять данные.
Еще интересные макросы
Немного любопытных макросов, которые не подошли к конкретному типу, но стоят того, чтобы обратить на них внимание.
Vote и Survey — макросы для создания голосований. Выше мы уже обсуждали похожий макрос Forms, который помогает делать опросы, эти же макросы помогут создать голосовалки для вашей команды.
Progress Bar Container и Progress Bar — можно создать прогресс-бар для любых нужд. Например, в команду вышел джун, который проходит онбординг новичка: с помощью этого макроса можно оформить прогресс его выполнения.
Как настроить Progress Bar Container:
Вставить макрос Progress Bar Container и настроить — указать текущий номер шага прогресса, текст подсказки при наведении на прогресс-бар или задать цвет с помощью CSS-стиля.
Поместить в контейнер макросы Progress Bar. В зависимости от того, сколько добавлено макросов, столько шагов прогресса и будет. В них можно настроить наименование шага и URL для гиперссылки по тапу на шаг.
Lock content — запрет для конкретных пользователей или групп на просмотр и изменение страницы.
«Записи в Блоге» — макрос будет отображать все записи в блоге вашего пространства.
Заключение
Важно уделять особое внимание оформлению любой документации. Макросы нужно использовать умеренно и не обвешивать ими всю документацию, как елку на Новый год.
Надеюсь, статья поможет оформить крутую и удобную документацию, которая соберет много лайков от ваших коллег. Буду рада вашей обратной связи!
И обязательно пишите, о каких возможностях Confluence вы бы хотели узнать подробнее. Во второй части поговорим о разметке страниц, метках и шаблонах. Не переключайтесь!
