Как в конфлюенс сделать раскрывающийся список

Как создать подвижное оглавление в статье Confluence

В последние пол года я активно работаю с документацией в Confluence — пишу полезные статьи, целью которых является облегчение работы команды тестирования. По ходу дела поняла, что некоторые тексты получаются настолько объёмными, что возникла потребность в структурировании таких массивов, поэтому научилась делать оглавление, которое передвигается рядом с текстом при пролистывании страницы. О том как создать такое оглавление хочу поделиться в своей первой статье для «Хабр».

1. Создание разметки страницы
   
   В первую очередь необходимо определиться где будет находиться оглавление и сделать с помощью инструмента «Разметка страницы», собственно, эту разметку. Вариантов здесь может быть несколько, на мой взгляд, лучше всего подходит такая разметка страницы, где основной массив текста находится слева, а оглавление — справа «Блок с двумя колонками с правой боковой панелью»:

Разметка появится на странице в виде двух блоков, обозначенных пунктирными линиями:

1. Важные нюансы в структуре текста
   
   При заполнении текста в блоке слева важно соблюдать правила:
   1. текст располагать только внутри блока (все символы, которые будут размещены вне этого блока, не попадут в оглавление);
   2. оглавление формируется автоматически с помощью макроса (подключается на самом последнем этапе, об этом ниже), логика этого макроса настроена следующим образом — он триггерится на разный формат текста, например: заголовок (формат текста «Заголовок 3») и подробное описание (формат текста «Абзац»), поэтому важно разбить объёмный массив текста на части, и у каждой такой части сделать заголовок и подробное описание разными форматами текста;
   3. формат текста можно регулировать с помощью раскрывающегося списка «Абзац» на панели инструментов «Confluence» слева:
   4. после того как написан заголовок, необходимо нажать «Enter», таким образом Confluence автоматически отделит заголовок от блока описания, после нажатия «Enter» происходит сброс настроек формата заголовка и блок подробного описания уже строится в формате «Абзац» — эта разница и позволит автоматически сформировать оглавление:
   5. после того как описан первый блок, необходимо вновь нажать «Enter»
      *каждый заголовок и каждый подробный блок описания должен заканчиваться нажатием «Enter» — это и позволит сформировать правильную структуру массива статьи:
2. Создание оглавления
   
   1. Кликнуть по блоку, обозначенному пунктирной линией справа, чтобы в этом блоке появился курсор:
   2. На панели инструментов Confluence выбрать инструмент «+» («Вставить прочий контент») и выбрать строку с макросом «Оглавление»:
   3. В предварительном просмотре уже видно как будет выглядеть оглавление — оно состоит из тех частей текста, к которым применён формат текста «Заголовок 3»:
      
   4. Если нажать на кнопку «Вставить» оглавление появится в блоке справа, но будет статичным, т.е. не будет передвигаться вслед за текстом при пролистывании страницы. Чтобы оглавление стало подвижным, нужно завершить настройки, для этого необходимо пролистать настройки макроса справа до пункта «Имя класса CSS» и ввести в строку значение «floating-block» (без кавычек):
      
   5. После нажатия кнопки «Вставить», подвижное оглавление появилось в блоке справа от статьи:
   6. После нажатия кнопки «Опубликовать», статья сохраняется, оглавление отображается справа от статьи, при этом блоки разделения с пунктирными линиями не отображаются. При клике на любой пункт оглавления, статья автоматически пролистывается до выбранного заголовка:

   

   У раскрывающегося списка с форматами текста «Абзац» есть иерархия значений списка — те значения, которые находятся вверху списка, имеют приоритет над теми, которые находятся под ними. Используя это знание, можно делать многоуровневое оглавление с подпунктами, если внутри одного текстового блока сделать несколько подзаголовков в разных форматах текста:
   

• Подготовка технической документации
• CSS

Как использовать макросы в статьях

Чтобы воспринимать информацию в статье было удобнее и быстрее, рекомендуется использовать инструмент макросы, входящий в состав Confluence. Макросы позволяют выделять информацию, добавлять в текст статьи различный контент, отображать содержимое вложенных документов и многое другое. В этой статья мы рассмотрим самые популярные макросы.

Список макросов находится в меню форматирования:

Вложения

Вложения — вывод в тексте статьи файлов, прикрепленных к ней:

Пример использования макроса Вложения:

Мультимедиа

Мультимедиа — вывод видео-плеера в текст статьи (видео необходимо прикрепить к статье):

Пример использования макроса мультимедия:

Ошибка визуализации макроса ‘multimedia’ : com.atlassian.renderer.v2.macro.MacroException: Cannot find attachment ‘Вебинар. Jira Confluence — с чего начать.mp4’

Раскрыть

Раскрыть — для добавления блока скрытого контента:

Панель

Панель — для добавления блока с выделенным текстом, например для описания документа.

Оглавление

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

Пример макроса Таблица контента смотрите в начале этой статьи.

Вывод документов Office

Вывод содержимого вложенных файлов в формате Word, Pdf, Excel:

Макрос Table Filter

Используйте этот макрос, чтобы добавить фильтр в таблицу с данными.

Конструктор формы

На второй вкладке » Конструктор » происходит настройка структуры формы и ее полей.

В правой части экрана отображаются страницы формы и ее элементы. Работа в конструкторе начинается с создания страницы — нажмите «Добавить страницу»:

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

Элементы и их описание

Заголовок — текстовый элемент, где вы можете указать основную тему своей формы.

Параграф — текстовый элемент. В нем может быть размещена какая-либо информация, которая должна отображаться в форме.

Короткий текст — текстовое поле, в котором может быть задан вопрос с коротким ответом. Например, имя или фамилия клиента.

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

Email — поле, в котором необходимо указать email.

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

Номер телефона — поле, в котором можно указать номер телефона.

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

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

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

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

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

Да/Нет — поле, в котором может быть задан вопрос с целью получения согласия, например, на получение почтовой рассылки.

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

Если вы поставите галочку в поле «Значение по умолчанию«, то в форме по умолчанию будет ответ «да».

Один вариант — поле, в котором может быть предложено выбрать один из нескольких вариантов ответа. Например, цвет товара — красный или синий.

Для данного поля может быть задан заголовок, варианты ответов, а также можно настроить видимость элемента и валидацию данных.

Нажмите на кнопку «Добавить вариант» и введите значение. Количество вариантов не ограничено.

Вы можете разрешить пользователю ввести свой вариант ответа, нажав на кнопку «Разрешить свой вариант«.

Элемент позволяет выбрать несколько вариантов ответа из предложенных. С помощью кнопки «Добавить вариант» добавьте возможные ответы.

Элемент можно сделать обязательным, а также ограничить количество выбираемых вариантов:

Выпадающий список — поле, в котором пользователю надо выбрать один вариант из выпадающего списка.

Для данного поля необходимо задать заголовок и варианты ответов. Нажмите на кнопку «Добавить вариант» и введите значение. Количество вариантов не ограничено.

Вы можете разрешить пользователю ввести свой вариант ответа, нажав на кнопку «Разрешить свой вариант«. При выборе этого варианта откроется поле для текста.

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

Также можно настроить видимость элемента и валидацию данных.

Если вы хотите предоставить пользователю возможность выбрать несколько вариантов ответа, кликните «Добавить множественный выбор«.

Обратите внимания, что при множественном выборе появляется новый тип валидации — «Ограничить количество выбираемых вариантов«.

Дата — поле, в котором предлагается указать дату, например, день рождения клиента.

Для данного поля может быть задан заголовок, а также можно настроить видимость элемента и валидацию данных.

Файл — поле, в котором к форме могут быть прикреплены файлы, например, фото. Максимальный размер файла – 20 мб.

Для данного поля может быть задан заголовок, а также можно настроить видимость элемента и валидацию данных.

Диапазон — диапазон выбора оценки. Для данного поля может быть задан заголовок, а также можно настроить видимость элемента и валидацию данных.

Кроме того, вы можете выбрать тип диапазона: в виде звезд или в виде чисел.

Вы также можете указать количество элементов (например, 5 звезд или 10 чисел).

Если в качестве типа диапазона вы выбираете числа, то обратите внимание, что отсчет начинается с 0.

Вы можете перетаскивать элементы формы, без особого труда располагая их в том порядке, который вам нужен. При наведении на элемент в верхней части появляется скопление точек. Наведите на них курсор, зажмите левую кнопку мыши и перетащите элемент, куда пожелаете.

Условие

Вы можете показывать некоторые элементы в зависимости от того, какой ответ пользователь дал на предыдущий вопрос. Для этого при настройке элемента нажмите на кнопку «Добавить условие» — откроются дополнительные поля (При каких условиях показывать следующее скрытое поле).

Укажите условие и значение, которое должен выбрать пользователь.

Далее добавьте элемент, который хотите показать, если пользователь выберет определенное значение в вопросе выше. Активируйте опцию «Скрытый элемент формы«:

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

Для добавления более сложных условий, например, переход между страницами формы в зависимости от ответов, настройте блок «Логика».

Валидация полей формы

У большинства полей доступен один или несколько типов валидации:

Проверить наличие в базе данных

Валидация через перечень телефонных кодов

(перечислите через символ «+» телефонные коды, которые разрешено указывать в форме)

Ограничить количество выбираемых элементов

(укажите минимальное и максимальное количество элементов, которые может выбрать пользователь)

Типы валидации «Проверить наличие в базе данных» и «Проверить наличие подписки» позволяют вам ограничивать отправку формы для некоторых пользователей. Например, вы можете разрешить отправку только зарегистрированным пользователям или запретить повторную отправку формы одним и тем же пользователем.

Проверить наличие в базе данных

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

При настройке формы необходимо выбрать:

• статус, который вы хотите проверять (существует или не существует),
• базу данных, в которой следует искать профиль,
• конкретное поле в базе данных.

Проверить наличие подписки

В момент отправки формы платформа проверит, подписан ли профиль, заполнивший форму, на определенный ресурс.

При настройке формы необходимо выбрать:

• статус, который вы хотите проверять (подписан, существует, не подписан),
• ресурс, подписку на который следует искать

Комментарий

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

Проектирование в Confluence

Меня зовут Маша, я работаю инженером по обеспечению качества в группе компаний Тинькофф. Работа QA предполагает множество коммуникаций с разными людьми из разных команд, а я к тому же была менеджером и лектором образовательных программ, поэтому моя карта коммуникаций была максимально широкой. И в какой-то момент я взорвалась: я поняла, что больше не могу, не могу, не могу заполнять адовые тонны нечитаемых таблиц и документов.

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

И вот, когда я немного остыла, я решила написать эту статью. Я расскажу о том, как можно нормально (даже порой удобно) вести разнообразную непродуктовую документацию. Надеюсь, что статья разлетится по сети и уровень адища в соседних с разработкой отделах хоть чуть-чуть снизится, а люди (и я в том числе) станут чуточку счастливее.

Инструменты

Продуктовая документация часто хранится рядом с кодом, и это хорошо. А непродуктовая документация обычно хранится где попало. Часто люди стараются переносить информацию из разных мест в Confluence, и мы не исключение. Так что весь дальнейший рассказ о нем.

Вообще Confluence — это продвинутый вики-движок. Он позволяет работать с данными в разных видах отображения: текст с форматированием, таблицы, разнообразные диаграммы. Это очень интересный и мощный инструмент, но если не уметь его готовить, то вы получите очередную свалку нечитаемых документов. Я научу вас готовить!

Макросы

Почти вся магия Confluence строится на макросах. Макросов очень много, и их можно комбинировать друг с другом. Они бывают платными и бесплатными, далее будут разные примеры макросов со ссылками на документацию для них.

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

Если макрос самодостаточный, то есть не требует вставки чего-то еще внутри себя, — он выглядит как блок.

Если для работы макроса нужно что-то поместить внутрь него, он выглядит как рамка.

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

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

Шаблоны

Помимо макросов есть удобный инструмент предзаполнения контента — это шаблон.
Шаблоны можно использовать при создании любой страницы: просто нажать на три точки рядом с кнопкой «Создать» и выбрать нужный шаблон.

Тогда в созданную страницу добавится весь контент, который есть в шаблоне.

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

Магия таблиц

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

Но даже такую замечательную сущность, как таблица, можно испортить. А можно удачно использовать и даже улучшить. Об этом ниже.

Фильтрация (платный плагин)

Любую огромную нечитаемую таблицу можно сделать чуть менее огромной и чуть более читаемой с помощью фильтрации. Для этого можно использовать платный макрос «Фильтр таблиц».

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

Вот представьте, что всю информацию по кандидатам на все вакансии записывают табличным списком. Естественно, неотсортированным — люди же приходят на собеседования не по алфавиту. А вам надо понять, проводили ли вы собеседование с конкретным соискателем раньше. Надо просто засунуть этот ад в макрос фильтра, добавить текстовый фильтр по фамилии — и вуаля, информация у вас на экране.

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

Сортировка (платный плагин)

С помощью волшебного макроса «Фильтр таблиц» также можно задать сортировку по умолчанию по любому столбцу и пронумеровать строки. Или нажать на любой столбец таблицы, засунутой в макрос фильтра, и произойдет сортировка по этому столбцу.

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

Сводные таблицы (платный плагин)

Теперь перейдем к кейсу поинтереснее. Представьте, что ваша таблица огромная и надо что-то посчитать по ней. Конечно, можно скопировать ее в Excel, посчитать нужное и выгрузить данные назад в Confluence. А можно один раз применить макрос «Сводная таблица» и получить тот же результат, только еще и обновляемый.

Например: у вас есть таблица, в которой собраны данные всех сотрудников — где они территориально находятся и какие должности занимают. Чтобы посчитать, сколько человек находится в каждом городе, вам нужно выбрать в макросе «Сводная таблица» строку, по которой агрегируются данные (местоположение) и тип операции (сложение).

Естественно, группировать можно по нескольким признакам сразу, все возможности можно посмотреть в документации.

Диаграммы (платный плагин)

Как я уже говорила, не все любят таблицы так сильно, как я. К сожалению, менеджеры в большинстве своем их вообще не любят. Зато все очень любят яркие цветные диаграммы.
Создатели Confluence об этом, безусловно, знали (наверняка у них тоже есть начальство, которое любит отчеты и диаграммы, куда же без него). Поэтому можно воспользоваться волшебным макросом «Диаграмма из таблицы». В этот макрос нужно положить сводную таблицу из предыдущего пункта, и вуаля — ваши серые скучные данные красиво визуализированы.

Естественно, в этом макросе тоже есть настройки. Ссылку на документацию к любому макросу можно найти в режиме редактирования этого макроса.

Простота агрегации

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

Метки

Плохо, когда люди хранят информацию в одной неструктурированной статье или огромной таблице. Еще хуже — когда части этой информации не только нечитаемо оформлены, но и раскиданы по просторам Confluence. Благо есть возможность собрать раскиданную информацию в одном месте. Для этого надо воспользоваться метками (знакомыми всем по соцсетям тегами).

На любую страницу можно добавить любое количество меток. Если нажать на метку, вы попадете на страницу агрегации, где есть ссылки на все материалы с этой меткой, а также с набором связанных меток. Связанные метки — это те, которые часто встречаются на одной странице.

Свойства страниц

На страницу можно добавить еще один интересный макрос для структурирования информации — «Свойства страниц». Внутрь него нужно подать таблицу из двух столбцов, первый будет являться ключом, а второй — значением свойства. Причем макрос можно скрыть со страницы, чтобы он не мешал читать контент, но при этом страница все равно будет отмечена нужными ключами.

Обратите внимание на ID — его удобно задавать, чтобы навешивать разные группы свойств на разные страницы (или даже разные группы свойств на одну страницу).

Отчеты

По меткам можно собирать отчеты. Например, макрос «Отчет о содержимом» собирает все страницы с определенным набором меток.

Но более интересный отчет — это макрос «Отчет по свойствам страницы». Он тоже собирает все страницы с определенным набором меток, но не просто выводит их список, а составляет таблицу (улавливаете связь с началом статьи?), в которой столбцы — это ключи свойств страницы.

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

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

Например, у вас есть множество страниц сотрудников, у этих страниц есть набор свойств про человека: какого он уровня, где находится, когда пришел в команду и так далее. Это свойства отмечены ID = employee_inf. И есть второй набор свойств на этой же странице, в котором собрана информация о человеке, как о части команды: какую роль человек выполняет, в какой команде находится и так далее. Эти свойства отмечены ID = team_inf. Тогда при сборке отчета вы можете вывести только информацию по одному айдишнику или сразу по двум — как удобнее.

Прелесть такого подхода в том, что каждый может собрать нужную для себя информационную таблицу, которая не будет ничего дублировать и будет обновляться при обновлении основной страницы. Например: тимлиду не важно, когда его разработчики устроились на работу, но важно, какую роль каждый из них выполняет в команде. Тимлид соберет себе отчет по команде. А бухгалтеру вообще все равно, кто какую роль выполняет, но важны должности — он соберет себе отчет по должностям. При этом источник информации не будет дублироваться или переноситься.

Итоговый процесс

Инструкция

Итак, мы можем красиво структурировать и эффективно агрегировать информацию в Confluence на примере использования макросов. Но в идеале нужно сделать так, чтобы новая информация сразу была структурированной и попадала во все уже используемые механизмы агрегации.

Тут на помощь придет связка макросов и шаблонов. Чтобы заставить людей создавать новые страницы в нужном формате, можно использовать макрос «Создать из шаблона». Он добавляет на страницу кнопку, по нажатию на которую создается новая страница из нужного вам шаблона. Таким образом вы заставляете людей сразу работать в нужном вам формате.

В шаблон, из которого вы даете создавать страницу, нужно заранее добавить метки, макрос «Свойства страницы» и таблицу нужных вам свойств. Также рекомендую добавить инструкции о том, какими значениями следует наполнять страницу, и значения свойств.

Тогда итоговый процесс будет выглядеть так:

1. Вы создаете шаблон для информации определенного типа.
2. В этот шаблон добавляете метки и свойства страницы в макросе.
3. В любом удобном месте создаете корневую страницу с кнопкой, по клику на которую создается дочерняя страница из шаблона.
4. Пускаете на корневую страницу пользователей, которые потенциально будут генерировать нужную информацию (по нужному шаблону, нажимая на кнопку).
5. Собираете себе отчет по свойствам страницы через метки, которые вы указали в шаблоне.
6. Радуетесь: у вас есть вся нужная информация в удобном формате.

Подводные камни

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

• Если вы решите поменять названия или состав свойств страницы, вам придется проапдейтить все уже созданные объекты, чтобы их данные корректно подтянулись в сводный отчет. Это печально, но, с другой стороны, заставляет детально продумать «архитектуру» вашего набора информации, что является весьма интересной задачей.
• Вам придется написать приличное количество инструкций о том, как заполнять информационные таблицы и пользоваться тегами. Но, с другой стороны, вы можете просто кинуть во всех нужных людей этой статьей.

Пример хранения непродуктовой документации

Через описанный выше процесс можно организовать хранение почти любой информации. Прелесть подхода в том, что он универсальный: когда пользователи к нему привыкают, они перестают генерировать бардак. Также большой (но не бесплатный) плюс — возможность собирать на лету разнообразную статистику и рисовать по ней красивые диаграммы.

Приведу пример нашего процесса ведения информации о команде.

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

Как видите, у нас развернутая таблица свойств и сразу есть инструкции о том, как именно вести данную страницу. Часть тегов проставляют сами сотрудники по инструкциям, в шаблоне только основные: тег карточки employee-card, тег направления direction-involve и тег команды team-qa.

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

По тегам можно увидеть разные сводки, например по qa-upgrade-plan отобразатся все задания на развитие QA. При этом каждый человек в своей карточке сотрудника ведет важную историю и свой план развития — создает вложенную страницу из шаблона планов развития.

Заключение

Ведите любую документацию так, чтобы за нее не было стыдно, а пользователям не было мучительно больно!

Очень надеюсь, что статья будет полезна и во всех документациях мира наступит порядок.