Станция «Confluence». Перевезти всё, что нажито непосильным трудом
Опыт перевода документации из Word в Confluence
Меня зовут Дина, я занимаюсь аналитикой в одной из команд «Ростелеком Информационные Технологии» (РТК ИТ). В статье хочу осмыслить полученный опыт переноса документации и поделиться своими соображениями. Возможно вы тоже думаете о переходе на базу знаний. Такой переход может занять больше времени, чем ожидается. Я расскажу как это было у нас. В конце подведу итоги: что получили и что потеряли.
Предпосылки переезда
Мы занимаемся разработкой системы поддержки продаж услуг связи Ростелекома. Система начала развиваться в 2008 году. С тех пор о ней написано довольно много разной документации, преимущественно в Word. Хранилищем этого богатства был SharePoint, сконфигурированный под наши нужды. Каждый аналитик, перед тем как взять в работу версию документа, оповещал коллег, затем выкладывал обновлённую версию и также оповещал. Каждый аналитик вел документацию на своем локальном компьютере.
Работа была налажена, и казалось, что менять тут нечего. Процесс подстроен под наши нужды и нужды заказчика. Однако в жизни течёт и изменяется, появляются новые требования. Когда-то были печатные версии документов и живые подписи. От этого отказались много лет назад и перешли на электронный документооборот. Но и этот процесс был формализован донельзя и занимал много времени.
Чтобы частное техническое задание можно было пустить в реализацию, сначала его неделю мусолили в электронной системе документооборота, где оно проходило через всех заинтересованных лиц. Далее нам возвращался ЛУЗ (лист учета замечаний), по которому нужно было внести правки, или обосновать, почему правки не требуются. Замечания могли дублироваться и даже противоречить друг другу, так как согласующие не видели чужих комментариев, рассматривая документ. После подробной «отработки ЛУЗ» документ отправлялся на новый круг согласования. Два круга были нормой, но могло быть и больше, если постановка вызывала дискуссии.
Усилия, которые требуются на примирение и поиск консенсуса, помноженные на бюрократию, выливаются в месяцы согласований. Для динамично развивающегося рынка телекоммуникационных продуктов это, мягко говоря, неприемлемо.
Вопрос назрел
Стали слышны речи об отказе от формализма как в самой документации, так и в процессах согласования. Другие команды РТК ИТ уже использовали Confluence, и ходили слухи, что согласование документации у них проходит не так формально и намного быстрее, чем у нас.
Одновременно с этим внутри команды бродили идеи о возможности совместного редактирования технического проекта, который мы должны актуализировать в ограниченный срок после релиза. При этом каждый аналитик вносит в него правки по своей задаче.
К тому же мы уже начали перерабатывать и сам технический проект, так как поняли, что он неудобен для использования. Он уже больше напоминал полотно, к которому куда-то вниз дописывают информацию из очередного технического решения. Ориентироваться в нем становилось всё сложнее. Возникла идея описания глобальных процессов системы со ссылками из них на более детальное описание каких-то особенностей реализации, подпроцессов и т.д. Нужны гиперссылки!
Прежде чем продолжить повествование, хочу подробнее рассказать о видах документации, которую мы ведем.
Виды документации
Текущая проектная документация по задаче: частное техническое задание (ЧТЗ), техническое решение (ТР), программа и методика испытаний (ПМИ), протокол приемо-сдаточных испытаний (ПСИ).
Технический проект — документ, разработанный по ГОСТ 34: пояснительная записка и описание автоматизированных функций из 13 отдельных многостраничных файлов. Каждый файл соответствовал выделенной функциональности или разделу в системе. Объемы этих файлов варьировались от 4 до 400 страниц.
Руководство пользователя — около сорока файлов разного размера. Исходники мы переводим в PDF для загрузки в систему. В системе, которую мы разрабатываем, каждый файл привязывается к определенной функциональности (пункту меню, разделу) для более удобного доступа пользователям.
Спецификации протоколов взаимодействия с внешними системами. У нас более 100 интеграций по различным протоколам. Часть спецификаций ведем мы, другие ведутся внешними командами. Тут полный зоопарк в наполнении и оформлении. Свои спецификации мы описывали в Word, другие команды используют Word, Confluence, Swagger или что-то подобное (доподлинно мне неизвестно). Нам их присылают либо в виде выгрузок, либо ссылками на пространство, где они ведутся.
Зачем всё тащить в confluence, а не оставить «где росло»
Не вся информация о системе хранилась в SharePoint. За годы работы аналитики (и не только они) обобщали разную полезную информацию о системе и процессах работы в файлах на локальных дисках, в Google-таблицах и на общих сетевых дисках. Это могли быть как просто какие-то «заметки», так и инструкции, которые очень пригождаются в работе.
В SharePoint загружали именно официальную документацию, о которой я писала выше. А могли и забыть загрузить актуальную версию — человеческий фактор. Это приводило к тому, что надо было искать того, кто владеет информацией. Он либо найдет у себя, либо скажет, где смотреть последнюю правильную версию, либо мы ничего не найдем.
Хотелось изменить процесс работы с документацией, чтобы:
можно было видеть актуальную версию документа моего товарища, которая нужна мне для работы, сразу, как только он ее написал;
несколько человек могли писать комментарии к одной и той же версии документа, чтобы при согласовании не приходилось собирать общую картину из разных файлов, полученных по электронной почте;
можно было одновременно редактировать файл технического проекта или руководство пользователя в тот момент, когда у меня есть на это время / вдохновение, не дожидаясь, когда его освободит мой коллега;
в самом техническом проекте добавить гиперссылки для перехода на другие сценарии, чтобы их не дублировать и не загромождать текущий сценарий;
ускорить поиск информации, чтобы всё хранилось в одном месте и не надо было помнить кучу пространств, где еще можно поискать ответ на свой вопрос.
Поскольку мы уже использовали Jira для ведения задач, то переход к Confluence выглядел гармонично. Это база знаний, как-никак, а знаний мы накопили много, и они продолжают множиться.
Этапы перехода
Переносить документацию мы начали в порядке ее востребованности нашей командой: от той, которая в работе практически ежедневно, к той, которой пользуемся реже. С высоты пройденного пути мне кажется, что этот подход помог команде быстрее адаптироваться к работе в Confluence.
Первые шаги
Сразу писать в незнакомом редакторе серьёзный документ страшновато. Многие сначала писали документ в привычном Word, а потом переносили более-менее готовую версию в Confluence. Стандартный набор инструментов в меню работает не так, как привыкли. Надо изучать какие-то макросы, среди которых есть дублирующие, непонятно чем отличающиеся. Например, нумерованный список: Nested Number List и Nested Number List ver 2.
Как я хочу:
Как это будет в Confluence:
Идеального сходства добиться кажется невозможно. Но! У нас есть умельцы:
Первопроходцы делились с коллегами своими открытиями. Появилась специальная «Тестовая страница», где есть примеры использования наиболее востребованных у нас макросов.
Проектная документация. Шаблоны страниц
Начали мы с того, что решили всю текущую документацию по новым задачам вести в Confluence. Хитрый ход, который заставил обучиться работе в Confluence даже тех, кто не спешил его осваивать.
Обычно для написания документоа в качестве «рыбы» использовали ранее написанный аналог по другой задаче. Поскольку разные аналитики могут вносить свои изменения в структуру, получилось, что в команде были немного разные форматы одних и тех же видов документов.
В Confluence такую «рыбу» можно сделать одну для всех. Можно создавать страницы по своим шаблонам. Мы собрались, обсудили наши текущие документы и договорились об одинаковых разделах и их содержании. Теперь при создании ЧТЗ, ТР, ПМИ, протокола ПСИ надо выбрать соответствующий шаблон. Создастся новая страница со всеми нужными разделами, примечанием, поясняющим, что там нужно описывать, и примером описания. Если надо что-то изменить в формате, вносим изменения в шаблон, и — вуаля! — новшества можно использовать в новых документах.
Технический проект. Дробить на части и собирать воедино
Следующим этапом был перенос технического проекта. Этого этапа я очень ждала, потому что это наиболее востребованный в работе документ, описывающий актуальную техническую информацию о системе. Хотелось сделать его более удобным для практического применения. На оформлении по ГОСТу заказчик больше не настаивал, что облегчало задачу и позволяло реорганизовать документ так, как нам хотелось. Сразу в едином дереве теперь видно не просто все тома технического проекта, но и все разделы этих томов.
Мы выделили общие сценарии на отдельные страницы. Настроили ссылки на них из других сценариев. Постарались сократить «портянки» и разбить их на логические модули. Нектороые страницы поменяли местами, как нам показалось логичнее. В Confluence это делается легко.
Документ оброс новыми страницами, описывающими архитектуру; даже некоторые скрипты записали в Приложение. Чтобы облегчить поиск по нашей громадине, сделали отдельную страницу «Поиск», которая помогает быстро искать именно по техническому проекту. Использовали макрос «Page Tree Search». На этой странице также есть ссылка на «помощь» по поиску в Confluence.
Глобально технический проект остался разбит на те же логические части, что и раньше (наши тома), только теперь они визуально крепче связаны вместе (единое дерево) и «сшиты» гиперссылками. Взаимосвязи процессов в системе стали видны лучше.
Я бы остановилась на этом. Мне уже всё нравилось, но я не одна в команде. Другим было неудобно переключаться между Confluence и SharePoint. Поэтому мы продолжили. Следующие два этапа хотели проскочить побыстрее и делали их параллельно.
Руководство пользователя. Опыт импорта и экспорта
Руководство пользователя никак перерабатывать не требовалось, поэтому большого энтузиазма у аналитиков работа по его переносу не вызывала. Ну, кто любит заниматься обезьяньей механической работой? К счастью, как раз в это время к нам пришла новая аналитик. Конечно, ей очень скоро предложили основательнее ознакомиться с системой через руководство пользователя. Нет, она не одна переносила эти тонны писанины с картинками, но львиная доля успеха принадлежит именно ей!
Поскольку мы не любим механической работы, то решили рассмотреть автоматизацию процесса с помощью импорта из Word. Однако быстренько всё закачать не очень получилось. Оказывается, всё форматирование «едет», картинки исчезают, таблицы узнать невозможно. Кто бы мог подумать?
Я не заметила, чтобы импорт особенно увеличил скорость переноса. С таким же успехом можно копировать и вставлять кусочки из вордовского исходника на страницу Confluence. Дело вкуса, как говорится.
Итак, перенести руководство пользователя получилось, осталось научиться выгружать его в PDF, чтобы потом загружать в нашу систему.
Стандартный экспорт в PDF выгружает только одну страницу. Чтобы выгрузить несколько, нужно обладать правами администратора. Управлять результатом выгрузки не получится. Если таблицу перекосит или подпись под рисунком к нему «прилипнет», остаётся только смириться.
Плагина для выгрузки в PDF у нас нет, зато есть Scroll Word Exporter. Поэтому мы выгружаем красиво в Word и приводим задачу к условиям той, решать которую мы уже умеем. Напомню, раньше исходники были в Word: мы их экспортировали в PDF и загружали в нашу систему на радость пользователям.
Основная идея работы с плагином проста: делаете файл Word, где задаёте стили, нужные для итогового документа, колонтитулы, содержание. Есть ключевые слова (переменные), которые можно вставить, например, название пространства, из которого документ выгружен, или дату выгрузки. Загружаете созданный таким образом шаблон в Confluence, задаёте ему имя. Далее при экспорте нужно будет его выбрать. Тогда выгружаемая страница (вместе с дочерними, если настроите) будет подвержена переработке по вашему шаблону. Путём не очень сложных экспериментов удалось добиться почти такого же вида руководства пользователя, каким оно было раньше.
Спецификации протоколов взаимодействия. Все звери по вольерам
У нас и раньше на SharePoint под каждую смежную систему была отведена определённая папка. Так что, строго говоря, в нашем зоопарке порядок был всегда. Теперь он немного изменился: вместо папок — страницы с подстраницами. Настроили шаблон для выгрузки наших спецификаций в Word, чтобы можно было отправить «красивый» документ внешним командам, не имеющим доступ в наше пространство Confluence.
Чтобы сохранить в нетронутом виде старания коллег от смежных систем, «чужие» спецификации вложили на соответствующие страницы «как есть» файлами или сделали ссылку на их ресурс. Удобно, что на той же странице можно оставить комментарии от себя о том, что и как используем, настройки / конфигурации и т. п. Раньше мы добавляли в папку со спецификациями текстовый файл с такими комментариями.
Итоги — что приобрели, что потеряли
Приобрели
Всегда актуальную документацию. Получается, что мы заменили два инструмента: SharePoint и Word на один. При этом исключили лишние действия: скачать / загрузить, извлечь / вернуть документ. И это незначительное исключение теперь исключает человеческий фактор вида «забыл выложить».
Более читабельный технический проект. Об этом уже много писала выше. Считаю главным достижением именно преобразование технического проекта, которые, к слову, продолжаются. Нет предела совершенству!
Удобство согласования документов. Раньше мы отправляли документ по почте разным адресатам, от которых ожидали комментариев/согласований. Соответственно, назад получали несколько версий одного документа с разным набором комментариев, которые надо обработать. Теперь все могут оставлять комментарии на одной странице, что значительно упрощает работу.
Возможность одновременной работы с одним и тем же документом. Стало удобнее актуализировать технический проект. Теперь аналитики не ждут друг друга, вносят правки, когда у них есть на это время.
Удобное сравнение версий и поиск изменений в документе. Confluence сохраняет абсолютно всю историю изменений документа. Сколько раз сохраняли страницу, столько у неё версий. Есть инструмент сравнения версий. Можно легко отследить, кто и когда внёс те или иные изменения, если это требуется.
Удобную базу знаний. В Confluence ведём не только документацию, там бурлит жизнь: ведутся инструкции и шпаргалки по текущей работе, информация о команде и процессах в ней. Есть раздел «WIKI» с информацией о системе, особенностях и нюансах, не вошедших в другие документы. То, что раньше передавали из поколения в поколение, из уст в уста, теперь зафиксировано на общедоступных страницах.
Потеряли
Независимость от сервера. Раньше аналитик мог работать даже при отсутствии интернета (какое-то время), так как документ был на локальном компьютере. Сейчас перебои в работе Confluence блокируют работу с документацией
Хороший текстовый редактор. Сложное форматирование Confluence неподвластно. При переносе документации из Word именно оформление пришлось адаптировать. Даже при простых операциях копирования и вставки текста можно получить неожиданный результат: нумерация сбивается, таблицы ведут себя нестабильно.
Удобное хранилище файлов. Не очень нравится мне и использование Confluence для хранения файлов. Да, их можно вложить в страницу, но инструмент не предназначен для работы с ними: сравнивать даты, размеры, заменять, копировать. Ну, это не файловый менеджер.
Скорость обучения новых сотрудников. Скорость обучения новых сотрудников. Хотя Confluence и «интуитивно понятен», всё же требуется некоторое время, чтобы научиться с ним работать. Тогда как с Word знаком каждый школьник.
Мои выводы
В заключение скажу, что работы по переносу документации мы выполняли в фоновом режиме, параллельно с основной работой. В один момент времени переносом занимались от одного до трёх (из десяти) аналитиков. Процесс занял примерно полтора года.
В итоге получили достаточно удобный инструмент, интуитивно понятный и при этом имеющий настройки, которые требуется изучать. Информацию добыть несложно, но требуется время на эксперименты.
Стали ли аналитики быстрее работать? С учетом того, что основная работа аналитика происходит в его голове, больших изменений не произошло. Однозначно сократился процесс согласования.
Confluence — рабочий инструмент. У любого инструмента есть некоторые «приятности», которые «строить и жить помогают». Когда в руках хороший инструмент, работа доставляет радость. Спрашивала некоторых наших аналитиков — Confluence нравится. У меня к нему остались вопросы, но в целом работать можно.
