Инструкция по работе с confluence

Уровень сложности
Простой

Время на прочтение
10 мин

Количество просмотров 10K

Привет, Хабр! Я Ульяна, старший аналитик в направлении продуктового и системного анализа в отделе 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-пространств, создавать опросы и голосования, переиспользовать контент в разных частях документации.

«Фильтр таблиц» помогает организовать табличные данные: навесить фильтры и сортировку. Нужно вставить таблицу в рамку и выставить нужные настройки.

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

Как настроить выборку и вставку таблицы:

1. Добавить макрос «выборка таблицы».

2. Задать уникальное наименование для выборки и вставить в рамку таблицу с данными.

3. Использовать макрос вставки выборки таблицы, чтобы вставить копию этой выборки.

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

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

Forms — Confluence позволяет делать различные формы с опросами и голосованиями. Все данные из форм можно отправить на электронную почту.

Нужно вставить макрос Forms, а в него все, что идет с приставкой Forms.

Multiexcerpt и Multiexcerpt include — макросы для свободного ввода.

Как настроить:

1. Добавить макрос multiexcerpt.

2. Задать уникальное наименование и вставить данные.

3. Вставить копию этой выборки, используя макрос multiexcerpt include (при необходимости).

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

«Отчет по задачам» — макрос помогает создать отчет из определенных источников, людей, статусов. Мы в команде часто используем его для retro, 3Amigo и MN, чтобы не терять зафиксированные todoшки.

«Отчет о содержимом» — макрос генерирует отчет о содержимом в формате таблицы на основе проставленных на страницах пространства меток. Мы этот макрос используем для организации прогресса RFC и RND.

Как настроить макросы внешнего контента

Макросы внешнего контента помогают настроить связь с Jira, отобразить данные из Figma, Miro и иных источников, построить различные отчеты и аналитику по связанному внешнему контенту.

Jira — макрос встраивает задачу или фильтр из Jira.

Structure.Gantt — макрос для отображения диаграммы Ганта в Confluence, если вы используете Jira Structure. Нужно только указать идентификатор вашей структуры. Можно выводить какую-то конкретную часть из Structure, настроить период автоматического обновления или оформление диаграммы.

«Время решения» — макрос отображает гистограмму времени, затраченного на решение запросов по проекту или фильтру из Jira.

«Гаджет состояния спринта» поможет визуализировать состояние и прогресс вашего спринта.

«Запросов в работе» — макрос покажет все задачи в работе в зависимости от заданных настроек. Данные отображаются для конкретных currentUser.

«Виджет коннектора» — макрос отображает внешний контент, нужно только указать ссылку.

Как настроить макросы навигации

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

Livesearch помогает встроить поле поиска на страницу Confluence. В поле по мере набора текста будут отображаться результаты поиска.

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

«Оглавление» — макрос создает оглавление текущей страницы на основании заголовков страницы

Page Tree — макрос отображает дерево страниц. Можно настроить страницу, для которой нужно отобразить дерево, ограничения, сортировку и добавление строки поиска.

«Якорь» — макрос позволяет создать якори внутри страницы, которые могут быть гиперссылкой.

Как настроить:

1. Вставьте макрос «Якорь» в месте, на которое хотите ссылаться, и придумайте имя.

2. Нажмите «Вставить ссылку» в верхней панели, чтобы сослаться на якорь.

3. Укажите имя якоря через #, если нужна ссылка на якорь в рамках той же страницы.

4. Укажите имя страницы и якоря через # в блоке «Ссылка», чтобы дать ссылку на якорь другой страницы в том же пространстве.

5. Укажите в блоке «Ссылка» ключ другого пространства, через двоеточие название страницы и якоря через #, чтобы дать ссылку на страницу из другого пространства. Например: MobileCore: Календарь отпусков#Мой якорь.

6. Укажите в блоке «Ссылка» ссылку на страницу, добавив синтаксис #:~:text= и конкретное слово или фразу, чтобы дать ссылку на конкретное слово или фразу. Например: https://wiki.ru/pages/viewpage.action?pageId=250575000#:~:text=Как настроить.

Как настроить макросы-отчеты

Макросы-отчеты помогают создать различные календари, построить отчеты по свойствам страниц, импортировать данные и преобразовать в отчет.

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

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

По данным из макроса «Свойства страницы» можно делать «Отчет по свойствам страницы». Этот макрос соберет всю информацию о свойствах конкретных страниц и выведет в виде таблицы.

Как настроить макросы с использованием CSS

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

Какие макросы используют CSS:

1. Div — блочный элемент. Нужен, чтобы выделить фрагмент в документе, который вы хотите изменить. Чтобы обратиться к нему, укажите атрибут class или ID с именем селектора.

2. CSS Stylesheet — создан, чтобы писать CSS-стиль и обращаться к созданным классам.

3. Clickable — помогает создать кликабельные блоки.

Создадим кликабельный блок с заголовком и картинкой для примера:

1. Создайте макрос с классом test-component-panel. В макросе можно задать наименование, стиль и язык кода, но мы ограничимся дефолтными настройками.

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

3. Добавьте новые классы: например, с настройками размера, цвета, отступов или со вставкой картинки.

4. Вставьте макрос CSS Stylesheet, чтобы наша ракета взлетела. В CSS Stylesheet добавьте CSS-стиль, и данные из кода будут обращаться к нашим классам и заполнять данные.

Еще интересные макросы

Немного любопытных макросов, которые не подошли к конкретному типу, но стоят того, чтобы обратить на них внимание.

Vote и Survey — макросы для создания голосований. Выше мы уже обсуждали похожий макрос Forms, который помогает делать опросы, эти же макросы помогут создать голосовалки для вашей команды.

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

Как настроить Progress Bar Container:

1. Вставить макрос Progress Bar Container и настроить — указать текущий номер шага прогресса, текст подсказки при наведении на прогресс-бар или задать цвет с помощью CSS-стиля.

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

Lock content — запрет для конкретных пользователей или групп на просмотр и изменение страницы.

«Записи в Блоге» — макрос будет отображать все записи в блоге вашего пространства.

Заключение

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

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

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

Как Confluence помогает вам как личности?

Помимо того, что  вы  будете лучшим товарищем по команде, использование Confluence может помочь вам стать лучшим лидером и сотрудником. Как? Когда вы начнете использовать Confluence, вы увидите, что это поможет вам:

✅ Делиться своими идеями и делиться ими с помощью хорошо структурированного контента

✅ Находить существенные ресурсы , с помощью которых вы будете делать свою работу

✅ Проводить мозговой штурм и документировать свои самые важные идеи

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

✅ Быть в курсе работы своей команды

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

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

Какова ваша роль в Confluence?

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

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

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

Как вы будете использовать страницы

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

Просматривайте страницы

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

Редактируйте страницы

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

Добавляйте комментарии к страницам

Оставьте отзыв или поделитесь своими мыслями с помощью функции комментариев . Вы узнаете больше о комментариях в будущих курсах.

Создайте новые страницы

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

Организовывайте страницы

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

Страницы содержатся в разделах!

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

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

👇 Вот как разделы и страницы соотносятся друг с другом.

Вы отлично начали! Далее вы узнаете больше о разделах и интерфейсе Confluence.

Отправьте статью себе на почту

07.10.2016

Предлагаем Вашему вниманию статью слушателя нашего курса «Разработка технических текстов и документации» Георгия Полищука, посвящённую одной из наиболее популярных платформ для организации совместной работы над информацией Atlassian Confluence, которую часто используют в том числе для организации процессов документирования.

Компания «ПроТекст» проводит курс «Техническая документация в Atlassian Confluence». Мы учим работать в программе «с нуля», но даже если вы уже научились основам работы в программе и у вас есть вопросы или что-то не получается — добро пожаловать на курс! Опытный преподаватель подскажет, поможет, научит.

Содержание

ВВЕДЕНИЕ

КРАТКО О ПРИНЦИПАХ РАБОТЫ CONFLUENCE

ДОКУМЕНТИРОВАНИЕ В CONFLUENCE

Задачи

Решения

Экспорт документации в файлы MS Word

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

Создание эксплуатационной документации для различных версий продукта

Привязка бизнес-процессов

Создание «динамических» отчетов

Импорт документов MS Word

Еще несколько полезных плагинов

ЗАКЛЮЧЕНИЕ

Введение

Австралийская компания Atlassian известна своими программными продуктами для управления проектами разработки программного обеспечения. Широкую популярность завоевали инструмент управления проектами и баг-трекер JIRA, а также система совместной работы над информацией Confluence.

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

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

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

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

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

Кратко о принципах работы в Confluence

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

На уровне пространства определяются права на просмотр, редактирование и комментирование статей, добавление файлов и тому подобное (рис. 5). Тот, кто создает пространство, по умолчанию становится его администратором.

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

Зарегистрированных в Confluence пользователей рекомендуется разделить на группы в зависимости от должностных обязанностей и принадлежности к проекту/команде, и затем присваивать права уже на уровне групп.

Кроме групп пользователей, специально созданных администраторами, в Confluence по умолчанию существуют следующие три группы:

• system-administrators (системные администраторы). Системным администратором становится пользователь, устанавливающий Confluence. Он имеет права назначать других системных администраторов, предоставляя им соответствующие права на глобальном уровне. Системные администраторы могут осуществлять все функции администрирования, включая предоставление прав пользователям;
• confluence-administrators (администраторы Confluence) могут осуществлять большинство администраторских функций (включая предоставление прав пользователям), кроме тех, которые могут поставить под угрозу безопасность системы;
• confluence-users. Это группа, в которую по умолчанию добавляется любой новый пользователь Confluence.

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

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

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

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

Макросы делятся на следующие категории (рис. 8):

• связанные с внутренним контентом: история изменений страницы и пространства, новости, список дочерних страниц, список вложений и тому подобное, в том числе макросы, позволяющие использовать контент данной страницы на другой странице;
• связанные с внешним контентом: связи с JIRA, подгрузка лент RSS, лента активности проекта;
• отвечающие за работу с диаграммами, графиками, рисунками;
• макросы для ведения коммуникаций, в том числе для добавления дискуссий в привязке к контенту страницы;
• для вставки на страницу контента MS Word, Excel, PowerPoint, вставка pdf-файлов, а также аудио и видео;
• для добавления метаинформации о страницах для ее использования в отчетах; метки;
• для навигации по контенту сайта: оглавление, результаты поиска, дерево страниц и тому подобное;
• макросы, с помощью которых можно создавать различные отчеты: по спискам пользователей, по метаинформации на страницах, меткам и так далее;
• макросы, связанные с форматированием: разметка страницы, столбцы, секции, примечания, предупреждения, блоки кода, ярлыки и ссылки на них и тому подобное.

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

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

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

Документирование в Confluence

Задачи

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

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

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

• связанные с требованием метаданные: например, информация о поставщике требования, дате поступления требования, а также ссылка на задачу JIRA;
• блок первичного («чернового») варианта требования для ведения обсуждений;
• блок формулировки требования для Технического задания с возможностью его автоматического включения в документ при экспорте;
• блок формулировки требования для Частного технического задания с той же возможностью.

При этом данная структура должна обладать возможностью тиражирования для создания большого количества требований.

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

Помимо перечисленных, существуют еще несколько частных задач:

1. необходимость отслеживать состояние проработки требования и степень его готовности для включения в документ. Другими словами, возможность создания цепочки статусов в привязке к странице требования с возможностью формирования по ним отчетности и оповещения ответственных пользователей о переходах от одного статуса к другому;
2. необходимость создания отчетов по требованиям с возможностью добавления новой метаинформации к требованию прямо из отчета: принадлежность требования к определенной категории (например, тому или иному направлению или модулю в составе разрабатываемого ПО), сроку исполнения; возможность добавления комментариев без перехода непосредственно к странице требования;
3. необходимость работы в Confluence с контентом файлов MS Word, то есть возможность импорта файлов doc- и docx-формата.

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

Решения

Экспорт документации в файлы MS Word

Проблема экспорта документации в docx-файлы решается использованием возможностей плагина Scroll Office. Он позволяет подгрузить в Confluence шаблон MS Word, в котором пользователь создает необходимые стили абзаца, таблиц, списков, заголовков, а также настраивает колонтитулы, оглавление, поля страницы и прочее в соответствии с ГОСТом. К примеру, плагин выгружает таблицы со стилем Scroll Table Normal. При создании шаблона пользователь должен создать стиль таблицы с таким названием и задать для него необходимые параметры.

Также на титульной странице шаблона можно добавить огромное количество тэгов для заполнения метаданными со страницы Confluence:

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

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

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

• Заглавная страница (с которой происходит экспорт иерархии)
  • Дочерняя страница 1
    • Заголовок 1
    • Заголовок 2
  • Дочерняя страница 2
    • Заголовок 1
    • Дочерняя страница 3
    • Дочерняя страница 4

будет иметь следующую структуру в документе:

Заглавная страница (Название документа)

1 Дочерняя страница 1

1.1 Заголовок 1

1.2 Заголовок 2

2 Дочерняя страница 2

2.1 Заголовок 1

2.2 Дочерняя страница 3

2.3 Дочерняя страница 4

Кроме того, со страниц Confluence при помощи макросов Scroll Office можно сделать следующее:

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

Таким образом, один раз разобравшись со стилями в шаблоне и научившись работать с макросами Scroll Office, вы решите все проблемы с переводом документации в формат MS Word.

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

Проблема возможности использования единой структуры требования в различных документах решается установкой плагина Scroll versions. Он позволяет создать страницы, контент которых может относиться к разным вариантам документации. К примеру, на странице требования можно создать два блока, один из которых попадает при экспорте в первый документ, а другой — во второй. При этом требование будет обладать единой структурой метаданных и относиться к одной задаче в Jira, формулировку требования для второго документа можно будет формировать, «имея перед глазами» формулировку первого, и тому подобное.

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

На следующем рисунке показан пример пространства, из которого при экспорте формируются два документа: Техническое задание и Частное техническое задание. Пространство показано «под углом» варианта ТЗ, на что указывает иконка в правом верхнем углу. Слева в дереве пространства серым цветом обозначены те страницы, которые не принадлежат к выбранному варианту («Раздел для ЧТЗ», «Раздел для ЧТЗ 2»). К обоим документам относится раздел «Требования к системе»: данная иерархия страниц привязана к обоим вариантам. На странице требования указана метаинформация и блок описания, которые не попадут ни в один из документов при экспорте; далее идут блоки формулировок требования для ТЗ и ЧТЗ.

Для создания такой структуры нужно, во-первых, активировать возможность добавления вариантов в установках пространства и создать необходимые варианты документации (рис. 11):

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

• Макрос «Свойства страницы» отвечает за использование значений полей находящейся внутри него таблицы в качестве метаданных.
• Макрос Scroll ignore позволяет не выводить на экспорт находящуюся внутри него информацию.
• Макрос Conditional Content служит для для привязки находящегося внутри него блока к соответствующему/им варианту/ам.

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

После этого при создании страницы данный шаблон можно будет выбрать наряду со стандартными (рис. 13).

Далее, необходимо создать страницы требований по шаблону, заполнив соответствующие поля и привязав страницы к созданным вариантам (рис. 14).

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

Также при наведении курсора на блок текста, не привязанный к текущему варианту, будет выведено соответствующее сообщение (рис. 16).

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

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

Создание эксплуатационной документации для различных версий продукта

Кроме вариантов документации, Scroll versions позволяет создавать ее версии. Версионнсть также настраивается на уровне пространства.

Как и в случае вариантов, к версиям можно привязать отдельные страницы (отсутствующие в другой версии) и создавать различные версии одной и той же страницы. Главное отличие от вариантов состоит в том, что создается несколько модификаций одной и той же страницы с отдельным контентом и отдельной историей изменений. Очередная версия страницы создается на основе предыдущей.

Версии можно сравнивать между собой как на уровне страницы (рис. 17), так и на уровне пространства.

Привязка бизнес-процессов

Для отслеживания состояния проработки требования можно использовать плагин Comala Workflows, с помощью которого есть возможность настроить бизнес-процесс прохождения требования по определенным этапам (например, «в проработке», «на обсуждении», «на рецензии», «согласовано»). Можно задействовать один из стандартных бизнес-процессов, входящих в комплектацию, либо создать собственные. Здесь также можно настроить систему оповещений пользователей о переводе страниц на новый этап, а по состояниям бизнес-процесса формировать отчеты. Помимо этого, существует возможность писать комментарии и ставить задачи непосредственно при переводе страницы на новый этап. Например, при переходе к этапу «на рецензии», можно, упомянув ответственного пользователя, написать, на что именно ему следует обратить внимание.

Создание «динамических» отчетов

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

Импорт документов MS Word

Импорт документов MS Word — встроенная функция. При импорте документа его разделы в зависимости от уровня заголовков можно преобразовать либо в отдельные страницы Confluence, либо в разделы на самих страницах.

Еще несколько полезных плагинов

• CA JIRA-Confluence Issue Macro — для переноса отдельных полей задач JIRA в Confluence. К примеру, разработчик описывает способ проверки прямо на странице задачи в Jira, и при создании документа «Программа и методика испытаний» данное поле подтягивается из задачи в документ. Таким образом, при изменении способа проверки в задаче эти изменения отразятся и в документе;
• Copy Page Tree — для копирования дерева страниц в другое пространство или в другой раздел данного пространства;
• io Diagrams for Confluence и Gliffy Diagrams for Confluence — для создания диаграмм;
• Label Manager for Confluence — для удаления, изменения и объединения меток по всему пространству;
• Link Preview for Confluence — предпросмотр ссылок. Особенно актуально для ссылок на вложенные документы, потому что без скачивания документа данный плагин позволяет тут же уточнить его содержание;
• Refined Theme for Confluence — для организации контента, деления пространств на категории и создания рабочего стола пользователя Confluence. По умолчанию в Confluence есть возможность упорядочивать пространства только с помощью меток. Refined Theme позволяет создать отдельные вкладки для разделов сайта (например, вкладки проектов), в которых можно группировать пространства. На самих вкладках также можно создать категории: например, техническая документация, внешние документы проекта и базы знаний;
• Talk — Inline Comments for Confluence — для добавления дискуссий в привязке к контенту страницы;
• Advanced Tables for Confluence — расширенная работа с таблицами: добавление возможностей сортировок, подсчета итогов, автонумерации строк и тому подобного.

Заключение

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

Тэги: Confluence, инструменты, опыт, организация работы