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, инструменты, опыт, организация работы