Как сделать содержание в confluence
Как сделать содержание в confluence
Предлагаем Вашему вниманию статью слушателя нашего курса «Разработка технических текстов и документации» Георгия Полищука, посвящённую одной из наиболее популярных платформ для организации совместной работы над информацией Atlassian Confluence, которую часто используют в том числе для организации процессов документирования.
Содержание
Введение
Австралийская компания Atlassian известна своими программными продуктами для управления проектами разработки программного обеспечения. Широкую популярность завоевали инструмент управления проектами и баг-трекер JIRA, а также система совместной работы над информацией Confluence.
Confluence была разработана в 2004 году и быстро зарекомендовала себя как одна из самых удобных систем организации совместной работы над контентом, позволяющая создавать базы знаний, делать публикации, вести обсуждения, работать с документацией, хранить файлы, доступные через Web, создать корпоративный информационный портал и многое другое.
Confluence построена на вики-движке и как вики-система представляет собой сайт, страницы которого могут быть отредактированы множеством участников. Каждая правка страницы сохраняется в истории изменений, просмотрев которую, можно выяснить, какие правки и кем именно были внесены, а также вернуться к определенной правке, сравнить между собой различные версии редактирования или удалить ту или иную ревизию страницы.
Таким образом, как вики-система Confluence обладает такими преимуществами как централизованный доступ к данным, возможность совместной работы над ними, а также версионность.
Рисунок 1 — Централизованный доступ к данным — главное преимущество Confluence
В данной статье не будут рассмотрены вопросы, почему нужно выбрать именно Confluence и чем данная система лучше других. Статья посвящена тому, как Confluence можно использовать для работы с требованиями и разработки технической документации проекта: формирования технического задания, программы и методики испытаний, а также создания руководств администратора, пользователя и так далее. Поэтому данный обзор скорее ориентирован на тех, кто уже выбрал Confluence или желает попробовать данный продукт в работе над технической документацией.
Сначала я вкратце расскажу о базовых принципах работы в Confluence, далее рассмотрю некоторые технические задачи, встречающиеся при создании документации и то, как их можно решить с помощью возможностей данного ПО.
Кратко о принципах работы в Confluence
Информация в Confluence размещается в специальных разделах — пространствах, которые являются контейнерами для страниц. Пространства позволяют разделять информацию между проектами или командами, могут иметь уникальную структуру данных и внешний вид в зависимости от потребностей проекта. Создать пространство можно как «с нуля», так и с использованием одного из шаблонов внешнего вида для более удобной организации данных (рис. 2).
Рисунок 2 — Выбор шаблона пространства
Рисунок 3 — Пример пространства. Слева изображено дерево страниц, справа открыта страница «Общие сведения»
На уровне пространства определяются права на просмотр, редактирование и комментирование статей, добавление файлов и тому подобное (рис. 5). Тот, кто создает пространство, по умолчанию становится его администратором.
Права доступа в Confluence разделены на три уровня — глобальный, уровень пространства и уровень страницы — и могут уточняться на каждом из них.
Зарегистрированных в Confluence пользователей рекомендуется разделить на группы в зависимости от должностных обязанностей и принадлежности к проекту/команде, и затем присваивать права уже на уровне групп.
Кроме групп пользователей, специально созданных администраторами, в Confluence по умолчанию существуют следующие три группы:
При необходимости права доступа можно настроить и для незарегистрированных в Confluence пользователей.
Рисунок 4 — Настройка прав доступа на глобальном уровне
Рисунок 5 — Настройка прав доступа на уровне пространства
В пространстве можно создать практически неограниченную иерархию страниц. Страницу можно создать как «с нуля», так и с использованием одного из шаблонов (рис. 6), в том числе созданных пользователем, имеющим соответствующие права. Подробнее о том, как создать шаблон для работы с требованиями, будет рассмотрено ниже.
Рисунок 6 — Выбор шаблона страницы
Для редактирования и добавления информации на страницы используется ряд базовых инструментов редактирования, которые доступны на панели в верхней части окна (рис. 7).
Рисунок 7 — Режим редактирования страницы
Для добавления файлов, диаграмм, оглавления, различных отчетов и тому подобного используются макросы.
Рисунок 8 — Макросы
Макросы делятся на следующие категории (рис. 8):
В Confluence используется система оповещений об изменениях контента страниц и пространств, на которые подписан пользователь. Также обратить внимание того или иного пользователя на страницу можно, просто поставив символ @ и начав набирать его имя (рис. 9). После сохранения страницы или комментария данному пользователю придет уведомление по почте.
Рисунок 9 — Упоминание пользователя
Confluence может обмениваться информацией с другими приложениями Atlassian, например, с системой управления проектами JIRA. Более того, основной выигрыш от использования Confluence получат именно те, кто планирует использовать ее вместе с остальными продуктами Atlassian.
Confluence, как было сказано выше, позиционируется как инструмент совместной работы над информацией, а поэтому данное ПО предполагает широкий спектр возможностей его применения. В зависимости от целей использования продукт можно кастомизировать под разнообразные нужды — в стандартную комплектацию входит довольно ограниченный набор базовых возможностей, а все остальная специфика настраивается подключением платных и бесплатных дополнений, которые доступны на сайте Atlassian Marketplace. Среди этих дополнений есть как собственные разработки Atlassian, так и плагины, написанные сторонними разработчиками. Именно установкой и настройкой специальных плагинов можно решить большую часть задач, встречающихся при использовании Confluence для создания документации.
Документирование в Confluence
Задачи
Во-первых, перед предприятиями, которые работают с госзаказами, зачастую стоит задача создания документации проекта по ГОСТу, что, помимо прочего, предполагает, что документы должны быть предоставлены в том числе в «бумажном», а не только «электронном» виде.
Таким образом, необходимо иметь возможность экспортировать контент сайта Confluence в оформленный по ГОСТу текст со всеми необходимыми отступами, правильным оформлением шрифтов, списков, таблиц, заголовков и прочего.
Во-вторых, работа с требованиями предполагает необходимость их единого источника, к примеру, для формирования таких документов как Техническое задание, Частное техническое задание, Программа и методика испытаний, а также для возможности создания отчетов и взаимодействия с инструментом управления проектами (например, с JIRA). Другими словами, задача состоит в создании структуры, которая вмещала бы в себя:
При этом данная структура должна обладать возможностью тиражирования для создания большого количества требований.
В-третьих, эксплуатационная документация (руководства пользователя, администратора и тому подобное), как правило, обновляется с каждой версией выпускаемого продукта, что предполагает необходимость такой структуры, которая содержала бы различные версии одной и той же страницы с небольшими изменениями контента.
Помимо перечисленных, существуют еще несколько частных задач:
Описанные выше проблемы создания технической документации решаются в основном благодаря использованию возможностей нескольких дополнений, о которых далее и пойдет речь.
Решения
Экспорт документации в файлы MS Word
Проблема экспорта документации в docx-файлы решается использованием возможностей плагина Scroll Office. Он позволяет подгрузить в Confluence шаблон MS Word, в котором пользователь создает необходимые стили абзаца, таблиц, списков, заголовков, а также настраивает колонтитулы, оглавление, поля страницы и прочее в соответствии с ГОСТом. К примеру, плагин выгружает таблицы со стилем Scroll Table Normal. При создании шаблона пользователь должен создать стиль таблицы с таким названием и задать для него необходимые параметры.
Также на титульной странице шаблона можно добавить огромное количество тэгов для заполнения метаданными со страницы Confluence:
Все это позволит использовать единый шаблон для выгрузки в соответствии с правилами стандарта большинства необходимых документов. Шаблоны можно подключить как глобально, так и на уровне пространства.
После экспорта заголовки дочерних страниц станут заголовками первого уровня в документе, дочерние дочерних — второго и так далее. Если внутри страницы Confluence присутствуют заголовки, они также будут преобразованы в заголовки соответствующих уровней в документе. К примеру, приведенная ниже структура в Confluence
будет иметь следующую структуру в документе:
Заглавная страница (Название документа)
1 Дочерняя страница 1
2 Дочерняя страница 2
2.2 Дочерняя страница 3
2.3 Дочерняя страница 4
Кроме того, со страниц Confluence при помощи макросов Scroll Office можно сделать следующее:
Таким образом, один раз разобравшись со стилями в шаблоне и научившись работать с макросами Scroll Office, вы решите все проблемы с переводом документации в формат MS Word.
Создание единой структуры требования для использования в нескольких документах
Проблема возможности использования единой структуры требования в различных документах решается установкой плагина Scroll versions. Он позволяет создать страницы, контент которых может относиться к разным вариантам документации. К примеру, на странице требования можно создать два блока, один из которых попадает при экспорте в первый документ, а другой — во второй. При этом требование будет обладать единой структурой метаданных и относиться к одной задаче в Jira, формулировку требования для второго документа можно будет формировать, «имея перед глазами» формулировку первого, и тому подобное.
К вариантам можно привязывать не только блоки внутри страниц, но и отдельные страницы. Таким образом, в рамках одного пространства можно формировать несколько документов с общими разделами.
На следующем рисунке показан пример пространства, из которого при экспорте формируются два документа: Техническое задание и Частное техническое задание. Пространство показано «под углом» варианта ТЗ, на что указывает иконка в правом верхнем углу. Слева в дереве пространства серым цветом обозначены те страницы, которые не принадлежат к выбранному варианту («Раздел для ЧТЗ», «Раздел для ЧТЗ 2»). К обоим документам относится раздел «Требования к системе»: данная иерархия страниц привязана к обоим вариантам. На странице требования указана метаинформация и блок описания, которые не попадут ни в один из документов при экспорте; далее идут блоки формулировок требования для ТЗ и ЧТЗ.
Рисунок 10 — Пример страницы требования, относящегося к нескольким документам
Для создания такой структуры нужно, во-первых, активировать возможность добавления вариантов в установках пространства и создать необходимые варианты документации (рис. 11):
Рисунок 11 — Создание вариантов документации на уровне пространства
Во-вторых, создать шаблон функционального требования примерно по следующей схеме (рис.12):
Рисунок 12 — Пример шаблона требования
К шаблону также рекомендуется добавить метку, по которой можно будет вести отчетность по страницам требований.
После этого при создании страницы данный шаблон можно будет выбрать наряду со стандартными (рис. 13).
Рисунок 13 — Создание страницы требования
Далее, необходимо создать страницы требований по шаблону, заполнив соответствующие поля и привязав страницы к созданным вариантам (рис. 14).
Рисунок 14 — Привязка страницы требования к вариантам
После этого на странице появится информация о том, что она привязана к указанным вариантам, а при наведении курсора мыши появится всплывающее окно, которое покажет, какие именно варианты задействованы (рис. 15).
Рисунок 15 — Сообщение о том, к каким вариантам привязана страница
Также при наведении курсора на блок текста, не привязанный к текущему варианту, будет выведено соответствующее сообщение (рис. 16).
Рисунок 16 — Сообщение о том, что контент не привязан к текущему варианту
Немаловажным преимуществом данного плагина также является возможность создания страниц с одинаковыми заголовками. Дело в том, что в стандартной комплектации названия страниц привязаны к постоянным ссылкам, что не позволяет создать страницы с одинаковыми названиями в пределах пространства. Scroll versions делает название страницы независимым от ее постоянной ссылки.
Варианты можно использовать также для создания документации на разных языках.
Создание эксплуатационной документации для различных версий продукта
Кроме вариантов документации, Scroll versions позволяет создавать ее версии. Версионнсть также настраивается на уровне пространства.
Как и в случае вариантов, к версиям можно привязать отдельные страницы (отсутствующие в другой версии) и создавать различные версии одной и той же страницы. Главное отличие от вариантов состоит в том, что создается несколько модификаций одной и той же страницы с отдельным контентом и отдельной историей изменений. Очередная версия страницы создается на основе предыдущей.
Версии можно сравнивать между собой как на уровне страницы (рис. 17), так и на уровне пространства.
Рисунок 17 — Сравнение версий страницы
Привязка бизнес-процессов
Для отслеживания состояния проработки требования можно использовать плагин Comala Workflows, с помощью которого есть возможность настроить бизнес-процесс прохождения требования по определенным этапам (например, «в проработке», «на обсуждении», «на рецензии», «согласовано»). Можно задействовать один из стандартных бизнес-процессов, входящих в комплектацию, либо создать собственные. Здесь также можно настроить систему оповещений пользователей о переводе страниц на новый этап, а по состояниям бизнес-процесса формировать отчеты. Помимо этого, существует возможность писать комментарии и ставить задачи непосредственно при переводе страницы на новый этап. Например, при переходе к этапу «на рецензии», можно, упомянув ответственного пользователя, написать, на что именно ему следует обратить внимание.
Рисунок 18 — Переход к новому состоянию бизнес-процесса работы с требованием
Создание «динамических» отчетов
С помощью Comala Canvas можно создавать «динамические» отчеты. К примеру, после создания требований необходимо бывает разделить их по определенным параметрам (готово/не готово, модуль, к которому оно относится, планируемые сроки исполнения и тому подобное), причем из-за большого количества требований бывает неудобно заходить на каждую страницу, чтобы вносить эти правки. В этом случае поможет отчет, прямо со страницы которого можно добавлять новую мета-информацию и комментарии к требованиям.
Рисунок 19 — Пример отчета
Импорт документов MS Word
Импорт документов MS Word — встроенная функция. При импорте документа его разделы в зависимости от уровня заголовков можно преобразовать либо в отдельные страницы Confluence, либо в разделы на самих страницах.
Рисунок 20 — Импорт документа: выбор уровня заголовка, заканчивая которым документ будет разделен на страницы Confluence
Еще несколько полезных плагинов
Заключение
В статье я рассмотрел пути решения технических проблем, с которыми столкнулся при создании документации в своей компании. Confluence хорош тем, что его можно адаптировать под различные условия в зависимости от специфики проекта или нужд организации. Свобода в организации контента — главное преимущество данного ПО. После того как вы настроите и научитесь использовать Confluence, он сослужит хорошую службу вашим коллегам – техническим писателям, аналитикам и менеджерам.
Создавайте контент и сотрудничайте
Основные достоинства Confluence Cloud — это эффективность и гибкость. Продукт позволяет без труда создать насыщенный динамический контент. При этом все начинается со страницы — динамического документа, в котором размещается контент. В этом руководстве вы научитесь использовать Confluence для создания и редактирования страниц, добавления контента, поиска неопубликованных черновиков страниц, ограничения доступа к странице и многого другого.
Если вы используете вариант Confluence Data Center или Confluence Server, узнайте из этого обучающего руководства, как создавать и редактировать страницы в Confluence.
Создание новой страницы
Создать контент в Confluence Cloud очень легко: просто нажмите Create (Создать) и заполните страницу текстовой информацией, таблицами, изображениями и другим содержимым. В отличие от традиционного документа Word, созданные в Confluence страницы динамически изменяются в режиме реального времени. Любой пользователь, имеющий доступ к сайту Confluence, сможет увидеть, что вы написали (конечно, если вы захотите это показать). В этом разделе вы узнаете, как выбирать нужный шаблон, поймете разницу между черновиками и опубликованными страницами, научитесь управлять доступом к просмотру, редактированию и комментированию страниц и использовать метки для упорядочения контента.
Шаблоны
Вместе с Confluence Cloud поставляются более 70 шаблонов. С их помощью можно создавать любые страницы: от протоколов собраний до требований к продуктам и маркетинговых планов. В шаблонах есть все необходимое для создания прекрасного, эффективного и динамического контента.
Чтобы создать страницу на основе шаблона, нажмите Create (Создать) и выберите нужный шаблон. Подробнее о шаблонах страниц в Confluence см. в нашей документации.
Если нужного шаблона нет в галерее, можно установить дополнительные шаблоны из Atlassian Marketplace, отредактировать существующие шаблоны с учетом потребностей команды или создать собственные шаблоны.
Черновики и опубликованные страницы
Значок: замок безопасностиПосле создания новой страницы и до момента публикации она остается в состоянии черновика, то есть отсутствует в дереве страниц, лентах событий и результатах поиска (после публикации страница появится во всех этих местах, если она не 
). Черновики сохраняются автоматически, даже если вы их не публикуете. Чтобы увидеть неопубликованные черновики, выберите в верхнем меню Recents > Drafts (Последние > Черновики).
Не хотите, чтобы все узнали о том, что вы опубликовали новую версию? Нажмите значок меню ••• (Другие действия), который находится в правом верхнем углу, рядом с кнопкой Close (Закрыть), и выберите команду Publish without notifying watchers (Опубликовать без уведомления наблюдателей).
Ограничение доступа к страницам
По умолчанию просматривать (а также комментировать и редактировать) страницы в разделе могут все, кто имеет доступ к разделу. Чтобы изменить права доступа к странице после ее публикации, нажмите значок в правом верхнем углу (при просмотре страницы она находится рядом с кнопкой Share (Поделиться)) и выберите нужный вариант из раскрывающегося меню. Подробнее об ограничениях доступа к страницам и о том, как эти ограничения взаимодействуют с правами доступа к сайту и разделам, см. в документации Confluence Cloud.
Почему доступ к страницам по умолчанию открыт?
Confluence имеет прозрачную интегрированную структуру и предназначен для предоставления доступа к нужной информации и контексту всем, кому это необходимо для эффективной работы. Когда все имеют доступ к проектам, целям и стратегии команды, проще обеспечивать согласованную работу команд и не допускать потери знаний в организации при изменении должностных обязанностей сотрудников или их увольнении.
Доступ к странице можно ограничить и до ее публикации. Просто нажмите значок рядом с кнопкой Publish (Опубликовать) во время редактирования чернового варианта. После ограничения доступа к странице ее не смогут просматривать даже те, у кого есть ссылка, но отсутствуют необходимые права доступа.
Метки
Для упорядочения контента можно добавлять метки страницам и вложениям. Метки помогают легко распознавать сходный контент и быстро его находить, используя фильтрацию результатов поиска по метке.
Чтобы добавить метку к редактируемой странице:
Редактирование существующей страницы
Страницы Confluence — это «живые», динамически меняющиеся документы, которые могут обновляться при изменении ситуации. Для обновления страницы используют программу редактирования, с помощью которой можно тщательно настроить внешний вид и функциональную сторону страницы.
Чтобы отредактировать опубликованную страницу, во время ее просмотра нажмите значок карандаша в правом верхнем углу или клавишу e.
Возможности редактирования
Контент создается в программе редактирования. Здесь можно форматировать текст, управлять макетом страницы и выполнять многие другие действия:
Можно также использовать расширенные возможности страниц, такие как действия или дорожные карты, и даже выполнять интеграцию с другими приложениями. Вот некоторые из наиболее популярных расширенных возможностей Confluence Cloud:
Настройте свой сайт и разделы
Прежде чем начать работу с этим обучающим материалом, оформите подписку на бесплатную пробную версию Confluence Cloud. С помощью этого руководства вы настроите свой первый проект. Не закрывайте вкладку, пока будете оформлять подписку. Мы подождем вас.
Это руководство предназначено для Confluence Cloud. Если вас заинтересовала версия продукта с самостоятельным управлением, перейдите по ссылке >>
Если вы используете вариант Confluence Data Center или Confluence Server, узнайте из этого обучающего руководства, как создавать и редактировать страницы в Confluence.
Шаг 1. Изучение разделов
Сайт Confluence разбит на разделы. Разделы — это наборы связанных общим содержанием страниц, с которыми работаете вы и другие участники команды или сотрудники организации. В большинстве организаций используется несколько типов разделов: разделы для команд, разделы проектирования ПО, разделы документации и разделы баз знаний.
Используйте разделы для команд, чтобы вовлечь участников команды в совместную работу для достижения масштабных целей и показателей OKR. Например, вы можете создать раздел для маркетинговой команды, чтобы она ориентировалась на OKR, была в курсе руководств по использованию брендов и основ рекламных сообщений и понимала общую маркетинговую стратегию организации.
Используйте разделы проектирования ПО для отслеживания отдельных инициатив и проектов. Например, можно создать раздел проектирования, который станет единым источником достоверной информации обо всем, что связано с новой функциональной возможностью, которую разрабатывает компания: от требований к продукту и технических характеристик до протоколов собраний и ретроспектив.
Используйте разделы документации для создания и упорядочения технической документации по продуктам и услугам, чтобы упростить ее дальнейшее применение.
Используйте разделы баз знаний для хранения и извлечения ответов на распространенные вопросы, например разъяснения политик или ИТ-решений. Если вы оформили подписку на Jira Service Management, можно интегрировать этот продукт с сайтом Confluence, чтобы клиенты получили доступ к статьям из базы знаний.
Используйте личный раздел в качестве «песочницы» для упорядочения своих заметок, отслеживания личных OKR и целей, а также черновых вариантов предложений по проектам, которые еще не попали в дорожную карту. Установите контакт с командой через записи в блоге. Это помогает познакомиться или сообщить, над чем вы в данный момент работаете.
Прежде чем создавать кучу разделов, подумайте о том, как организация будет использовать Confluence Cloud. Вот некоторые типовые примеры использования.