Если в вашей компании документация живет в папках на разных дисках, теряется при обновлениях, сложно определить, к какому релизу относится тот или иной документ, а фраза «Кто знает, где последняя актуальная версия?» стала ритуалом, эта статья для вас. Привет! Я Роман Люкшин, системный эксперт‑аналитик «БАРС Груп». Два года назад мы прошли через этот хаос и нашли выход. Расскажу, как объединили аналитиков и технических писателей в GitLab по соседству с разработчиками и превратили документацию в «код» с историей версий.

В B2G‑проектах стандартные способы редактирования и отслеживания изменений (Google Docs, «Яндекс Диск», рецензирование в текстовых редакторах и т. д.) не подошли для документов, оформленных по шаблонам и ГОСТам 19 и 34.

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

• редактированием занимается больше одного аналитика;

• необходимо учесть замечания в разрезе релизов;

• нужно отслеживать, кто, что и когда внес в системную постановку;

• нужно быстро вернуть наработки, которые были несколько итераций назад.

Для технического писателя. ИС живет в разрезе релизов, и соответственно каждый релиз должен сопровождаться документацией: ЧТЗ, ПМИ, РП и т. д. Документация оформляется по ГОСТу, то есть один и тот же документ, например руководство пользователя (далее — РП), клонируется на количество релизов — уже выпущенных и планируемых. Из этого вырастают свои сложности:

• редактированием занимается больше одного технического писателя;

• необходимо учесть замечания в разрезе релизов;

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

• непонятно, как определить, что документ согласован и это актуальная версия.

Требования для самих себя

Мы с командой сформулировали, какие требования нужно внедрить, чтобы рабочий процесс на проекте стал структурированным и понятным:

• корректировки должны вноситься сразу в документ по шаблону/ГОСТу, без лишних комментариев рецензирования внутри файла;

• корректировка должна учитывать уже выпущенные и планируемые релизы;

• прозрачное отслеживание, кто, что, когда и на основании чего внёс корректировку;

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

• быстро находить актуальный документ в разрезе видов документов и релизов, учитывая, что редактированием занимается большая команда.

Выбор решения

Мы рассматривали решения от известных вендоров, но для наших задач они не подошли: они были рассчитаны на «легкие» текстовые форматы (т.е. не подходили для бинарных форматов вида *.docx) или имели ограниченный функционал по контролю изменений — вроде истории изменений в текстовом редакторе или на облачных дисках. Одним словом, отсутствовал полноценный контроль версий: изменения не отслеживались, история правок не сохранялась, восстановить любую предыдущую версию было нельзя.

С учетом того, что в компании разработчики уже пользовались GitLab для выполнения своих задач при разработке ИС, мы решили переиспользовать те же подходы в своей работе «не для программирования».

Все началось с переговоров с архитектором на проекте и согласования с ним выделения для аналитиков своего репозитория в GitLab, а затем — с выбора клиента для работы в этой платформе.

Что мы сделали для переноса процессов в GitLab:

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

2. Выбрали клиента для работы с GitLab TortoiseGit. Аналитики и технические писатели привыкли хранить файлы у себя локально. Этот клиент обеспечил безболезненный переход на систему версионирования файлов.

3. В Confluence разработали инструкцию по установке Git и работы с ним.

4. Разработали регламент работы с репозиторием и ведения документов/файлов.

5. Провели обучение по работе с Git и техническую консультацию в первые 2 недели после запуска.

Эти мероприятия позволили снизить сопротивление команды и помогли команде быстро освоить новые инструменты.

Что получилось в итоге

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

Теперь всегда можно узнать кто, что и когда менял:

Можно определить, какая версия документа актуальна, и быстро найти ее — без лишних вопросов в чатах и долгих поисков среди задач в Jira:

Незначительные нюансы в использовании нового подхода

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

Сложное форматирование в файлах типа *.doc (табуляция, переносы, встроенные шаблоны и стили, форматирование и т. д. — одним словом, когда это не просто файл формата .txt) усложняет процесс при одновременном редактировании файла и последующем слиянии несколькими участниками/аналитиками. Приходится разрешать конфликты, а авторазрешение конфликтов на таких типах файлов срабатывает не совсем корректно, особенно на объемных документах — могут стили слететь, табуляция измениться и т.п.

Но здесь мы нашли быстрое решение, которое не доставило дискомфорта или как-то затормозило процесс.

• Создали заранее отдельную группу в мессенджере Telegram.

• Разработали шаблоны сообщений в разрезе типов.

Т.е. прежде чем добавить документ в общую ветку необходимо сверить в чате, что никто его не держит на себе. Пример взаимодействия:

Результаты

Раньше поиск актуального файла мог занимать до 4 часов: письма, чаты, расспросы «А это точно последняя версия?». Теперь на это уходит 5–10 минут. Достаточно знать релиз и тип документа — дальше помогают структура репозитория и история коммитов.

В прошлом остались правки «не в тот» документ. Если раньше вдруг кто-то брал в работу устаревший файл, то потом приходилось 3 часа восстанавливаешь нужную версию. Сейчас такого просто нет: для каждого релиза есть своя единственная правильная ветка и свой файл. И все изменения привязаны к нему. Ошибиться стало куда сложнее. Среднее время согласования версии документа перед выходом релиза тоже сократилось — с четырех часов до одного. Всем понятно, что именно ушло в релиз.

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

«БАРС Груп» принимает активное участие в развитии Цифровой экономики России и создает цифровые решения для реализации национальных проектов, а также в импортозамещении программного обеспечения — более 80 решений компании зарегистрировано в реестре российского ПО. «БАРС Груп» стремится к непрерывному обновлению и технологическому лидерству. Рассказываем о наших продуктах и ИТ-трендах в Telegram-канале.