Confluence как сделать раскрывающийся текст

Как создать подвижное оглавление в статье 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, чтобы систематизировать и оформить техническую документацию?

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

Меня зовут Таня Дудо, и я уже 6 лет помогаю людям и командам обмениваться знаниями внутри компаний. Для этого использую Confluence. Да-да, ту самую wiki-систему, которую часто называют неудобной и несовременной. Сегодня выступлю ее адвокатом-обозревателем: расскажу про 7 полезных макросов для систематизации и оформления контента и наглядно покажу, как они работают.

Дисклеймер: с марта Atlassian не продают лицензии в Россию напрямую. Но если у вас уже есть, никто не запрещает ей пользоваться. На сайте Atlassian есть развернутая документация по установке Confluence и Jira. Она охватывает практически все аспекты. Вот, например, одна из статей.

В чем проблема с Confluence или почему я решила написать этот текст

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

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

Рекомендую к прочтению тем, кто:

• недавно начал с ней работать,
• уже использует и ищет способы сделать работу с Confluence более комфортной.

Что такое макросы и зачем они нужны

Макросы — это программные алгоритмы действий, «упакованные»‎ в понятный графический интерфейс. Если проще, это внутренние инструменты Confluence, которые помогают делать документацию понятнее и удобнее.

Чем макросы круче текстовых редакторов?

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

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

В Confluence макросов много — больше 5 тысяч , но я сосредоточусь на трех группах. Это:

• форматирование контента,
• интеграция внутреннего контента,
• интеграция внешнего контента.

Их можно называть «группами быстрого улучшения»‎ — они помогут сделать вашу доку читабельнее всего в пару кликов.

Где находятся макросы

Макросы можно добавить в статью в режиме редактирования. Они прячутся в верхней панели инструментов, за кнопкой с названием «Вставить прочий контент»‎.

Самые популярные макросы — например, «Оглавление»‎ и «Галерея»‎ — лежат в выпадающем меню. Больше возможностей скрываются за строчкой «Другие макросы»‎.

В библиотеке макросы рассортированы по группам. В левой части интерфейса можно сразу перейти к нужной группе.

Если подходящего макроса не нашлось, через кнопку «Найти еще макросы…»‎ можно перейти в Atlassian Market и изучить платные и бесплатные дополнения, совместимые с вашей версией Confluence.

Макросы-блоки и макросы-рамки

Макрос может быть самодостаточным и не требовать вставки чего-то (например, текста, изображений или ссылок) внутри себя. В таком случае он выглядят как блок.

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

Представьте: вам нужно спрятать под кат какой-то текст. Тогда можно использовать макрос «Раскрыть»‎: внутрь рамки помещаем текст, а после сохранения ок окажется внутри раскрывающегося меню.

Внутрь одного макроса-рамки можно помещать сколько угодно других макросов. Главное, чтобы в пирамиде была логика. Так, например, можно сделать пирамиду из раскрывающихся пунктов, или спрятать содержание статьи, если оно слишком объемное. Или добавить макрос форматирования текста.

Макросы форматирования: подсказка, предупреждение, примечание и блок кода

Зачем нужны:

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

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

Пожалуй, самый распространенный пример разноформатного подхода — это выделение подсказки, предупреждения и примечания.

Наверняка вы видели, как в самом начале текста капслоком написано «ВНИМАНИЕ»‎, и после этого идет абзац красного текста. Или подсказка отмечена звездочкой, а пояснение дано внизу страницы курсивом, как в печатных книгах.

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

Как использовать

В Confluence нашли изящное решение: унифицировали макросы «Подсказка»‎, «Предупреждение»‎, «Примечание»‎ и «Информация»‎.

В режиме редактирования они выглядят как макросы-рамки, внутри которых можно разместить текст.

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

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

Макросы для интеграции внутреннего контента

Зачем нужны:

• создают «зеркало»‎ статьи или ее отрывка в другом пространстве,
• поддерживают автообновление: достаточно внести правки в оригинал, и все интеграции обновятся сами,
• помогают быстро перейти из «зеркала»‎ в оригинальную статью и углубиться в нужный материал.

Бывает, что одна статья полезна для нескольких команд. Чтобы не дублировать ее в разных пространствах, можно использовать макросы «Включить выборку»‎ и «Включить страницу»‎.

Выборка — это небольшой отрывок из исходной статьи, а страница — полное «зеркало»‎ всего текста.

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

Чтобы включить цитату из одной статьи в другую, нужно:

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

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

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

Если нужно процитировать статью целиком, то на помощь придет макрос «Включить страницу»‎. Здесь после выбора макроса нужно ввести название статьи, которую будем транслировать на этой странице. Дополнительно включать выборку на исходной не нужно.

Макросы интеграции внешнего контента

Зачем нужны:

• позволяют размещать контент из внешних источников без дополнительных авторизаций,
• можно вставить задачи из Jira и видеть актуальный статус, не переходя в таск трекер,
• взаимодействие с интерактивным виджетом происходит прямо в Confluence.

В Confluence можно интегрировать контент из внешних источников. Это очень выручает, когда не вся документация хранится в одном месте и есть разница в форматах.

Самый простой пример такой внешней интеграции — добавление на страницу задач из Jira.

Представьте: проводите встречу, записываете meeting notes в Confluence и по итогам определяете задачи. Как их записать, чтобы исполнители точно знали, что нужно сделать и к какому сроку? Завести их в таск-трекер, а потом привязать к странице с результатами встречи.

Таски добавляются через макрос «Фильтр\проблема Jira»‎ — достаточно ввести код проекта и номер задачи. В Confluence подтянется ее название и актуальный статус.

Еще один полезный макрос интеграции внешнего контента — «Коннектор виджета»‎. С его помощью на страницу можно добавить любой контент из интернета, будь то видео с YouTube, Google-документ или таблица. Все будет отображаться прямо в Confluence без дополнительных авторизаций.

Например, можно собрать галерею из выступлений коллег. На скриншоте — наша подборка докладов сотрудников Selectel.

Где больше узнать про макросы

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

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

Больше полезной информации по работе с Confluence можно найти в корпоративном университете Atlassian Univercity или на ютуб-канале Atlassian.

Научитесь использовать Confluence, как это делают в Atlassian

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

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

Используйте Confluence не только для обработки текстов, но и для совместной работы

«Кто любит электронную почту? Никто», — говорит Блейн Баркер, старший менеджер по цифровому маркетингу.

Для новичков страницы Confluence кажутся похожими на знакомый текстовый процессор, поэтому они используют их соответствующим образом. Однако Confluence может гораздо больше. Сотрудники Atlassian осознают масштабы недоиспользования возможностей. Например, благодаря Confluence можно сократить объем электронной корреспонденции на 30–50 %. Используя теги, комментарии и общий доступ к страницам Confluence для совместной работы, команды могут реже полагаться на электронную почту и другие каналы связи. Готовы повысить эффективность командной работы с помощью Confluence? Мы снабдим вас советами от опытных пользователей.

СОВЕТЫ ПО ПОВЫШЕНИЮ ЭФФЕКТИВНОСТИ СОВМЕСТНОЙ РАБОТЫ КОМАНД С ПОМОЩЬЮ CONFLUENCE

• Создайте страницу, на которой вы определите способ общения между участниками команды и укажете каналы для разных типов взаимодействия.
• Перенесите общение из чата и электронной почты в Confluence. Оставляйте отзывы, выбирая нужный фрагмент текста с помощью функции встроенного комментирования. Вам больше не придется переключаться между вкладками, чтобы найти пункт 4 на странице 2.
• Отправляйте еще меньше сообщений. Для этого делитесь страницами с коллегами, чтобы они автоматически получали уведомления Confluence, когда вы вносите изменения.
• Делитесь ссылкой на интерфейс редактирования, а не на опубликованную страницу: режим редактирования позволит просматривать работу участников в реальном времени. Просто нажмите значок «+» рядом с изображением профиля, когда находитесь в режиме редактирования.

Выйдите за рамки вики и визуализируйте контент

«Испробуйте все доступные способы, чтобы сделать контент более наглядным», — говорит Даниэль Данненберг, руководитель по персоналу.

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

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

СОВЕТЫ ПО ВИЗУАЛЬНОМУ ПРЕДСТАВЛЕНИЮ И МАКЕТАМ СТРАНИЦ В CONFLUENCE

• Выделяйте важную информацию на странице с помощью макросов «Информация», «Совет», «Примечание» и «Предупреждение».
• При форматировании страницы используйте макеты для достижения оптимального визуального эффекта. Вы можете использовать макет страницы по умолчанию или настроить количество и ширину столбцов в зависимости от контента и целей.
• Наполните свои страницы интересными элементами и добейтесь привлекательного внешнего вида, добавив изображения и эмодзи. Они не просто разбивают текст и привлекают внимание читателей, но также передают эмоции и другие оттенки, чего не может сделать текст.
• Поместите на страницу раскрывающиеся элементы с помощью функции Expand (Развернуть), которая позволяет показывать или скрывать определенный контент для разных заинтересованных лиц. Так вы можете скрыть информацию, предназначенную не для всех читателей.
• С помощью функции Excerpt (Цитата) можно отображать элементы одной страницы на других страницах, не создавая копий. Эта функция очень важна для поддержания единого достоверного источника информации.

Держите заинтересованных лиц в курсе дел, сократив количество собраний

«Знания — ничто, если люди не могут их найти», — говорит Кристен Форд, руководитель программы по подбору персонала.

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

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

СОВЕТЫ О ТОМ, КАК ДЕРЖАТЬ УЧАСТНИКОВ КОМАНДЫ В КУРСЕ ДЕЛ С ПОМОЩЬЮ CONFLUENCE

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

Найдите время для освоения основных функций Confluence

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

В Atlassian решение Confluence играет роль виртуального офиса. Именно там сотрудники Atlassian проводят значительную часть своего рабочего времени, занимаясь планированием, обдумыванием, проектированием и совместной работой.

Когда инструмент занимает такое важное место в работе, имеет смысл потратить время на изучение всех его возможностей. Это потребует дополнительных усилий, однако они многократно окупятся в будущем благодаря экономии времени и энергии.

СОВЕТЫ ПО ОСВОЕНИЮ CONFLUENCE

• Какой главный вывод сделали сотрудники Atlassian после освоения Confluence? Команда с косой чертой — это сила! Если на странице Confluence нажать клавишу «/», раскроется меню с множеством возможностей. Все эти действия — от простых (добавление списка задач, эмодзи или дат) до расширенных (встраивание досок Trello, файлов Dropbox и презентаций PowerPoint) — можно выполнить при помощи команды с косой чертой. Уделите несколько минут, чтобы изучить возможности команды с косой чертой, и вы сэкономите себе много часов в будущем.
• Шаблоны — еще одна возможность, которая нравится сотрудникам Atlassian. Скорее всего, в обширной галерее шаблонов Confluence найдется подходящий шаблон для вашего проекта, поэтому никогда не начинайте по умолчанию с чистого листа. Команде Atlassian особенно нравятся следующие шаблоны: 90-дневный план, справочник для сотрудников, ретроспектива и стратегический план.
• Чтобы повысить окупаемость инвестиций в освоение Confluence, сделайте эту систему частью культуры компании и основным местом обмена знаниями для всех сотрудников. При поиске информации сотрудники Atlassian всегда сначала обращаются к Confluence. Чтобы реализовать такой подход в своей компании, начните акцентировать внимание новых сотрудников на Confluence во время их адаптации. Кроме того, руководителям тоже нужно использовать Confluence, чтобы подать пример всей организации. Тогда и остальные сотрудники начнут вести работу по такому принципу.

Шесть других важных советов по работе с Confluence

1. Просматривайте все задания в одном окне. Нажмите изображение профиля в правом верхнем углу и выберите Tasks (Задания).
2. Упорядочивайте страницы с помощью дерева страниц. Это облегчит поиск и позволит изменять структуру страниц в дереве путем перетаскивания.
3. Дублируйте страницы вместе с дочерними элементами. Вместо того чтобы дублировать все страницы по очереди, можно скопировать дерево страниц целиком. Выберите в меню More actions (Другие действия) пункт Copy (Копировать) и установите флажок для включения дочерних страниц.
4. Ограничивайте доступ к страницам. Прозрачность — это здорово, но иногда бывает нужно поработать над страницей в рамках небольшой группы. Используйте значок ограничений в правом верхнем углу страницы, чтобы разрешить доступ только основным заинтересованным лицам.
5. Добавляйте ссылки к изображениям. Это простая функция, но она необходима многим пользователям, например дизайнерам, которые хотят сослаться на исходные файлы или справочные материалы в Figma или Dropbox.
6. Используйте копирование и вставку из творческих программ. Еще один полезный совет для дизайнеров: вы можете копировать изображения, видео и другой контент в Confluence прямо из творческих программ, таких как Photoshop. Для этого не нужно сохранять файлы и выполнять их импорт.

Совместная работа: подход Atlassian

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

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

Благодарим Би Джей Шоне, Блейна Баркера, Кори Скотта, Даниэль Данненберг, Эмили Кастро, Жана Гонсалкорала, Кристен Форд и Майлза Кэя за ценную информацию.

Заполнение полей с выбором из справочника

Например, в поле «Диагноз» необходимо ввести первые символы кода диагноза.

При нажатии на кнопку «Поиск» (лупа) напротив поля «Диагноз» отобразится форма для поиска диагноза по следующим вариантам:

• поиск диагноза в дереве диагнозов с разбивкой по коду МКБ.

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

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

• Нет меток