конфлюенс что это в банке
Как не превратить корпоративную базу знаний в хаос: наш опыт борьбы с Confluence
С корпоративной базой знаний для разработчиков обычно есть проблема — она либо превращается в пустоту, потому что нет мотивации ее наполнять или ответственного человека, либо — в заполненный вещами балкон из советской квартиры, все вносят свой вклад, но пишут хаотично, информация быстро устаревает, и ее не всегда успевают обновлять.
Как этого избежать, ну или хотя бы снизить возможные издержки? Как сделать вашу корпоративную базу теплой и ламповой? Попробую ответить.
Документация в стиле «коллаб»
Есть такой подход, collaborative documentation, изначально он появился в сфере медицины, когда принятие решение о постановке диагноза принимается коллегиально пациентом и несколькими врачами.
Яркий пример в сфере IT — это Google Docs, Wiki, Github, любая система, где есть внутренние конвенции и возможность совместной работы над проектом.
Идея в том, чтобы как можно раньше включить в работу над документацией разработчиков, экспертов, критиков, вместе выявлять пробелы.
Зачем это вообще нужно?
Во-первых, снизить bus factor — это узкие места в корпоративных знаниях, где количество обладателей знания стремится к единице. Нужно перемещать такие знаний из головы разработчика, из whiteboards, тикетов, разговоров на кухне в единое пространство, чтобы все могли с ними работать и вносить вклад.
Во-вторых, для упрощения вхождения новичков в проекты, что особенно важно для распределенных команд и команд с некоторым количеством аутсорс-разработчиков, а также для тех компаний, у кого очень специфичная сфера бизнеса, и шанс найти готового специалиста равен нулю.
В-третьих, для формирования доброкачественной корпоративной культуры, прозрачности «не на словах». Разработчик в такой среде четко понимает точки профессионального роста, какие еще технологии он может опробовать в компании, чему научиться.
Что делать-то?
Документацию в рамках корпоративной базы знаний может писать любой участник команды, нужно упростить для них эту возможность, тогда они будут чувствовать себя владельцами результата — причастными.
Однако, обязательно нужен человек, который возьмет на себя функции архитектора информации — задаст единые правила, структуру, логику, стиль, будет правильно размещать документы в пространствах.
Откройте возможность редактирования и создания документов участникам команды, предварительно договорившись о правилах игры. Автоматизируйте эти правила по максимуму — не полагайтесь на команду, создайте шаблоны, помечайте контент тегами автоматически, настройте выгрузку из репозитория в базу знаний (об этом хочу сделать отдельную статью, кстати).
Важно, чтобы разработчики видели, что в корпоративную Wiki документы не уходят умирать. Важный принцип: definition of done внутреннего документа, это момент, когда в него внесли правки или комментарии, то есть собственно, момент коллаборации. В этом его ценность, на него хотят тратить время. Не дополняют — значит, плохо налажен процесс доставки, внедрения поиска, или инструмент неудобен.
Потенциальные проблемы такого подхода — это накапливание правок и комментариев как снежного кома, за ним сложно уследить, часто создаются дублирующие документы.
Чтобы этого не случилось, можно и нужно: А. Задать команде вектор, набор правил и усложнить процесс не следования им (пример, мы в Confluence спрятали кнопку «Создать» и сделать обязательным выбор шаблона). Б. С умом разграничивать права и настроить процессы правок удобно для того, кто отвечает за архитектуру информации.
И тогда наступит идеальный мир
Несмотря на эти ограничения, сама структура базы знаний, единое именование страниц, применение лейблов, будут стимулировать их искать и создавать знания, чтобы например не отвечать на постоянно повторяющиеся вопросы.
Еще один лайфхак, который мы применили — всегда включать в документы бизнес-контекст, даже если это описание библиотеки или класса или чек-лист по задаче, важно понимать, что это значит для клиента.
А теперь к практике
Далее будет часть про «Как», какие внутренние возможности Confluence (да, у нас используется стек Atlassian) можно использовать, чтобы реализовать эти принципы.
Шаблоны
Мы создали готовые шаблоны для разных видов документов, которые чаще всего пишем — техническая спецификация, how-to, чек-лист. Их можно настроить в панели админа пространства. Шаблоны нужны, чтобы, создавая документ, разработчик не видел перед собой пустую страницу, в нем уже есть инструкции, что написать в том или ином разделе. Если вы хотите, чтобы документы определенного вида попадали в один раздел и по ним отображалась метаинформация (это удобно, например, для описания компонентов сложного продукта или набора микросервисов по одной схеме), то создайте blueprint, это как шаблон на максималках.
В них мы настроили разметку страницы, заголовки, где останется только заменить несколько слов, шапку со статусом, изображения, таблицы, блоки кода, и даже переменные.
Переменные — это преднастроенные элементы контента, которым дальнейший редактор документа должен придать значение, например, ввести текст или выбрать из списка.
Также к шаблону можно заранее, если это узкий вид документа добавить теги, можно упомянуть пользователей как ревьюеров, например, если есть четкий поименный workflow по утверждению, Jira macro, и прикрепить тикет из Jira. Наш опыт показывает, что можно покрыть шаблонами до 80 процентов задач.
Разметка страницы
Еще один важный элемент — это создание понятной и красивой страницы приземления в командном пространстве. Для этого мы используем разметку страницы (page layout) и макросы Панель, Колонка и Секция.
Ниже показываю пример одного из наших пространств команд разработки.
Используйте понятные названия страниц. Как вы возможно знаете, Confluence не поддерживает одинаковые наименования страниц в пределах одного пространства. Поддерживайте понятные названия страниц, например
Плохое название Python
Хорошее название Python Styleguide для команды внутренних сервисов
Лейблы
У Confluence есть некоторые ограничения поискового алгоритма, связанные с индексацией контента. А для корпоративной базы знаний именно находимость и связность — это самые актуальные вопросы. У нас в базе знаний есть целая статья, называется How to beat the Confluence Search, если хотите, я поделюсь ей в комментариях.
Для преодоления этих ограничений мы используем систему лейблов. По сути, это теги, которые помечают тематику контента, а зачем позволяют агрегировать контент определенной тематики в одном месте в виде своеобразного RSS Feed (макрос Content by Label). Так у нас настроены предметные указатели.
Если у вас уже сотни страниц в базе, то советую начать со следующих упражнений:
Confluence для публичной базы знаний: меняем дизайн и настраиваем разделение по языкам
У нас есть шесть продуктов, которые используют в России и за рубежом. Это значит, что документация к ним должна быть в одном месте, но разделена по продуктам и языкам.
Раньше мы использовали MediaWiki, но со временем она устарела. От платформы мы ожидали так же хорошую вёрстку статей, гибкий поиск и внутренний редактор текстов. В качестве альтернативы выбрали Confluence.
В процессе стало ясно, что возможностей этой платформы из коробки тоже недостаточно для всех наших задач. Пришлось докупить плагин Scroll Viewport и потратить некоторое время на его настройку.
Вы можете посмотреть, что в итоге получилось, а я расскажу, как меняла дизайн, настраивала разделение по языкам, внутренний поиск и индексацию.
Меняем дизайн
Компания начала переносить документацию с движка MediaWiki на Confluence год назад. Но когда я приступила к проекту, Confluence выглядел стандартно, предыдущий разработчик добавил наш логотип и скрыл ненужные анонимному пользователю элементы. К запуску надо было привести документацию к нашему стилю. Дизайнеры подготовили макеты, а я должна была их сверстать.
Но дело в том, что сам Confluence даёт очень мало гибкости в стилях и скриптах, а возможности из коробки нетривиальны для понимания и использования, да и непривычны веб-разработчику.
Отмечу, что Confluence — это Java-приложение, а вовсе не веб-сайт с привычными бэкендом и фронтендом. В разделе Внешний вид можно добавить таблицу стилей или настроить пользовательский HTML, но этого недостаточно для полноценного редизайна. Поэтому для вёрстки мы купили плагин Scroll Viewport. Тут-то и началось самое интересное.
Плагин Scroll Viewport
Scroll Viewport — это плагин для Confluence, который позволяет создавать темы, используя привычный редактор кода и файловый менеджер. С его помощью можно писать стили, работать с шаблонами страниц, добавлять изображения, настраивать поиск.
Темы создаются для пространств. Пространства в Confluence — это сущности контента, в которых хранится информация по одному проекту. У нас есть пространство для продуктов: ISPmanager, BILLmanager и т. д., а также для главной страницы. У пространства есть ключ, заголовок, ряд настроек и, собственно, тема.
Редактирование темы в Scroll Viewport: разметка, стили и html
Начнём осваивать Scroll Viewport. Когда плагин установлен и включён, надо кликнуть на шестерёнку и далее — Основные настройки — раздел Scroll Viewport — Themes.
Выбираем, копируем или создаём тему и нажимаем Edit. Открывается редактор темы Scroll Viewport.
Обратите внимание, Scroll Viewport рекомендует не создавать тему с нуля, а брать за основу Scroll WebHelp Theme.
Редактор темы Scroll Viewport: слева структура темы, сверху название файла, в основной части сами файлы
Когда тема создана, можно приступить к её настройке. Зададим разметку и структуру страниц, добавим стили и скрипты, а потом перейдём к редактированию HTML-разметки элементов контента.
Разметка: редактируем, добавляем классы и выводим однотипные элементы в цикле
Структура страниц по типу
В корне темы находятся основные шаблоны: page.vm, search.vm, error.vm, а также изображение-обложка темы thumbnail.png.
Шаблон “page.vm” задаёт структуру всех страниц темы. Здесь можно редактировать html и с помощью переменных placeholders задавать, где будет выводиться контент. Плейсхолдеры обращаются к контенту пространства или данным пользователя (заголовок материала, название пространства, имя автора), с их полным списком можно ознакомиться в хелп-центре разработчика Scroll Viewport.
“page.vm” обращается к шаблонам, которые лежат на уровень ниже, в папке “include”, и оборачивает их в теги и блоки. В этом файле (page.vm) мы собираем страницу по кусочкам, и дополняем разметку всеми необходимыми атрибутами html-документа. Именно здесь мы указываем doctype, прописываем head и body.
Составные элементы страницы
В папке “include” лежат кусочки страницы. По названиям файлов можно догадаться, какой за что отвечает:
Стилизация: добавляем стили, изображения и скрипты
Внутри папки “assets” хранятся файлы js и css. Так как мы не создавали тему с нуля, там уже содержатся файлы от разработчиков Scroll Viewport.
Чтобы кастомизировать стили, лучше создать новый css-файл и подключить его в head шаблона страницы. Файлы, которые начинаются на theme, содержат в себе правила базовой темы Scroll Viewport. Их стоит редактировать в случае, когда новые стили упираются в базовые. Будьте внимательны, удаляя и добавляя правила, помните об иерархии селекторов, она может выручить.
В “assets” я также добавила папку с изображениями и папку с файлами шрифтов. Файловый менеджер работает не идеально, добавить папку в нужную директорию нельзя, поэтому пришлось схитрить. Я создала папку на своём компьютере, добавила в неё файл, а потом загрузила в нужную директорию драг-энд-дропом. Как только папка создана, с загрузкой файлов проблем нет.
При создании нового дизайна мы учитывали возможности плагина и ориентировались на уже существующие темы в Scroll Viewport, поэтому внутри assets/js я задержалась ненадолго. Внесла небольшие изменения в существующие файлы скриптов и добавила файлы нужных библиотек. Если изменения будут более значительными, со скриптами придётся разобраться детальнее.
Редактор html-разметки контента статьи
Благо, всегда можно поискать плагины, и, какая удача, нужный нашёлся почти сразу. Это Confluence Source Editor. После его установки можно в режиме редактирования статьи прошерстить и старый добрый гипертекст. Наконец-то!
Плагин Source Editor
В Scroll Viewport верстаем шапку, сайдбар, футер и задаём стили. Контент верстаем с помощью Source Editor. Всего я создала две темы: для страниц статей и для главной страницы документации.
Настройки Viewport пространства: применяем тему
Когда тема создана, её надо связать с пространством. Для этого в настройках пространства нужно создать Viewport. Viewport — это то, что связывает пространство и тему. Только создав эту сущность, можно применить стили темы для пространства.
Войдите в пространство нужного продукта, откройте Настройки пространства — Дополнения. Здесь можно создать Viewport и управлять им: задавать темы, типы контента, разрешения, домен и путь.
Форма для связи пространства с темой, создания Viewport
Выбрать тему
На вкладке Themes представлены все созданные темы и одна тема по умолчанию, которая появляется вместе с плагином Scroll Viewport. Выберите тему и примените к пространству.
Вкладка Content позволяет выбрать тип контента, к которому будет применяться тема. Она нам наименее интересна, так как ключ пространства подтягивается автоматически.
Настроить адреса
На вкладке URL можно выбрать домен и путь, по которому будет открываться пространство, а также задать структуру адресов. Она так же понадобится, чтобы разделить документацию на два домена по языкам.
Есть два типа структуры URL:
Но нужно учесть, что при выборе многоуровневых адресов URL будет зависим от названия статьи. Изменится название — изменится и адрес статьи. Если выбрать одноуровневую структуру, адрес будет менее читаем и понятен, но перестанет зависеть от заголовка страницы.
Мы выбрали многоуровневый тип структуры и читаемые адреса, но нам придётся следить за изменением названий статей и вовремя настраивать редиректы. И идеальный вариант мы всё ещё ищем. Мы также используем краткие ссылки, которые всегда ведут на статью и не меняются, такую ссылку можно найти в разделе Информация о странице.
Включить тему
Во вкладке Permissions можно обозначить, каким пользователям будет доступен просмотр пространства с применением Viewport.
Чтобы анонимные пользователи видели документацию только в заданном дизайне, нужно поставить две галочки:
Настраиваем разделение по языкам
В Scroll Viewport такие настройки предусмотрены, но если просто ввести отличный от основного домен во вкладке URL в поле Domain Name, два домена не заработают. Это особенность плагина Scroll Viewport.
Надо настроить Reverse proxy, чтобы запросы пользователей передавались Confluence и там разруливались на два домена — см. инструкцию Scroll Viewport (конфигурации для Nginx и TOMCAT). После этого надо выключить режим совместного редактирования или внести дополнительные изменения. Теперь можно указывать один из двух доменов в настройках Viewport.
Темы для разных языков
Применить одну тему к пространствам на разном языке не получится, потому что тема включает в себя не только стили, но и шаблоны страниц. Это означает, что язык элементов, которые выводятся не переменными, не меняется. Например, текст-плейсхолдер в строке поиска, контакты в футере и др. Так что пришлось делать отдельные темы для пространств на русском и английском языках.
Фактически я создаю идентичные по стилям темы, но вот шаблоны для них различны, в основном по части текста. Это излишество и дублирование, да, но иного способа я пока не нашла. К тому же тема регулирует и работу поиска тоже, а это ещё один аргумент в пользу разделения по языкам.
В итоге у меня получилось четыре темы: две для главных страниц на русском и английском, и ещё по две для страниц контента для каждого языка.
Настраиваем поиск по сайту
Параметры поиска настраиваются в файлах из папки “include”. Внутри них мы задаём параметры поиска:
Где искать
По умолчанию поиск работает только по текущему пространству. Например, в пространстве ISPmanager — только по статьям об ISPmanager. Если нужен поиск по списку пространств, в настройках include-quicksearch.vm нужно указать их ключи.
Форма поиска для отдельного пространства
Форма поиска по списку пространств
Как выводить результаты
Как будет выглядеть список с результатами поиска, задаёт шаблон include-search.vm. В моём случае у каждой найденной ссылки есть заголовок, описание и название пространства, к которому относится статья. Здесь же можно указать, что пользователь увидит, если поиск ничего не найдёт.
Из фрагмента шаблона ниже видно, что результаты поиска выводятся в цикле с использованием переменных-плейсхолдеров. Результатов поиска может быть довольно много, поэтому внизу страницы сделали пагинацию. Подробное руководство по шаблонам страниц поиска можно посмотреть в документации по поиску Scroll Viewport.
Как выглядит страница поиска
Все шаблоны первого уровня, расположенные в структуре рядом с page.vm, переопределяют структуру страницы в зависимости от ее типа. Так search.vm задаёт вёрстку страниц поиска, а error.vm — страниц ошибок.
Остаётся задать стили элементам, возможно добавить скрипты, и наша тема становится функциональной, выполняет задачи и выглядит согласно дизайну.
Настраиваем индексацию
Чтобы настроить индексацию, нужно положить карту сайта в корневую папку. Но у нас нет корневой папки, ведь Confluence — это Java-приложение, а не сайт. Что делать?
Подсказка нашлась в документации Scroll Viewport. Внутри пространства разводящих страниц, где хранится главная, надо создать новую статью, назвать её sitemap.xml и расположить на уровень ниже главной.
Расположение важно, потому что, как отмечают в документации, файл карты не будет доступен для Viewport с префиксом пути “/”. Как раз такой префикс у Viewport пространства главной страницы.
Статья sitemap.xml в структуре пространства
Мы помним, что в Confluence заголовок статьи и её URL связаны. Когда страница создана и уже открывается по адресу docs.ispsystem.com/sitemap-xml, займёмся её корректным отображением. Такой формат URL не совсем типичен, но вполне нам подойдёт.
Карта сайта должна быть без лишних тегов и стилей, ведь она создаётся для поисковиков. Чтобы заданные раньше стили не применялись к карте сайта, надо создать шаблон include-sitemap.vm и скопировать в него содержимое подготовленной карты сайта — sitemap.xml. Это будет выглядеть следующим образом:
Теперь для страницы sitemap.xml создадим отдельное условие в шаблоне page.vm, чтобы стили и структура из шаблонов применялись для всех страниц, кроме карты сайта.
Для условия понадобится идентификатор. Узнать его можно, открыв страницу, а затем нажав Многоточие — Информация о странице, в конце адресной строки и будет идентификатор. Теперь пишем условие:
После описанных манипуляций путь к карте сайта можно указать в панелях вебмастера Яндекс и Google, и начнётся индексация.
В целом вопрос индексации для меня остаётся открытым. Не до конца понятно, как индексируются страницы контента Confluence. Нужно подумать, как автоматизировать процесс.
Как внедрить Atlassian Jira + Confluence в корпорации. Технические вопросы
Планируете внедрение ПО Atlassian (Jira, Confluence)? Не хотите допустить жестоких ошибок в проектировании, которые потом придётся решать в последний момент?
Тогда вам сюда — рассматриваем внедрение Atlassian Jira + Confluence в корпорации с учётом различных технических аспектов.
Здравствуйте, я являюсь руководителем центра компетенции по продуктам Atlassian в РСХБ (Россельхозбанк) и отвечаю за развитие Системы управления жизненным циклом (СУЖЦ) построенной на программных продуктах Jira и Confluence.
В этой статье опишу технические аспекты построения СУЖЦ. Статья будет полезна всем, кто планирует к внедрению или занимается развитием систем построенных на ПО Atlassian в корпоративном окружении. Статья не требует специальных знаний и рассчитана на начальный уровень знакомства с продуктами компании Atlassian. Статья будет полезна администраторам, владельцам продукта, руководителям проектов, архитекторам, всем кто планирует внедрение систем на основе ПО Atlassian.
Введение
В статье будут рассмотрены технические вопросы внедрения Системы управления жизненным циклом (СУЖЦ) в корпоративном окружении. Давайте вначале определим, что же это значит.
А что значит корпоративное решение?
Это значит решение:
А что такое Система управление жизненным циклом (СУЖЦ)?
Если коротко, то в нашем случае это Atlassian Jira и Atlassian Confluence — система предоставляющая инструментарий для организации коллективной работы. Система не «навязывает» правила организации работы, а предоставляет разнообразный инструментарий для работы, это и Scrum, и Kanban-доски, и водопадная модель, и масштабируемый Scrum и т.д.
Название СУЖЦ не является отраслевым термином или общеупотребительным понятием, это просто название системы в нашем Банке. СУЖЦ для нас не является системой баг-трэккинга, не является системой Управления инцидентами и системой Управления изменениями.
В системе конечно же присутствует функционал и для баг-трэккинга, и для регистрации инцидентов, и для управления изменениями. И для тех или иных задач этот функционал используется. Но нельзя сказать, что все баги или все инциденты или все изменения регистрируется в нашей системе. В каждом конкретном случае своя специфика. Если какое-то подразделение использует Jira и ведёт там изменение, то для данного изменения, данная команда может решить вести там все баги, все изменения, все инциденты. Но это локальное решение одной отдельной команды, для одной конкретной задачи.
Что в себя включает внедрение?
Внедрение решения состоит из множества технических и организационных вопросов:
Особенности Atlassian
Компания Atlassian является лидер ом во многих сегментах:
Продукты компании Atlassian обладают всеми необходимыми корпоративными функциями. Я отмечу следующие особенности:
Техническая архитектура
Лицензирование
Вопросы лицензирования Atlassian заслуживают отдельной статьи, тут упомяну только общие принципы.
Главные вопросы с которыми мы встретились — это вопросы лицензирования редакций Data Center. Особенности лицензирования для редакций Server и Data Center:
Функциональный объём внедрения
Базовая поставка ПО Atlassian включает огромное количество возможностей, но зачастую возможностей, предоставляемых системой сильно не хватает. Иногда даже простейшие функции недоступны в базовой поставке, поэтому без плагинов не обойтись практически при любом внедрении. При этом важно понимать, Jira — это платформа, здесь можно запрограммировать любой функционал и плагины — это платная реализация дополнительного функционала. Для системы Jira мы используем следующие плагины (картинка кликабельна): 
Для системы Confluence мы используем следующие плагины (картинка кликабельна): 
Комментарии к таблицам с плагинами:
Заключение
Итак, мы рассмотрели технические особенности внедрения системы на основе продуктов Atlassian. Предложенное решение представляет собой одно из возможных решений и хорошо подходит для корпоративного окружения
Предложенное решение — масштабируемое, отказоустойчивое, сдержит три среды для организации разработки и тестирования, содержит все необходимые элементы для совместной работы в системе и предоставляет широкий спектр инструментов для управления проектами.
С радостью отвечу на вопросы в комментариях.