О себе
Всем привет. Меня зовут Никита, я руковожу командой Цикл-ОН. Мы уже более 5 лет ведем проекты по заказной разработке ПО и, как и многие, сталкиваемся с необходимостью разработки не только качественного кода, но и документацию на продукты. В нашей нише особенность, что заказчи��и живут в парадигме ГОСТа. Я бы здесь хотел оставить небольшую заметку о нашем опыте — как то, что для начаиналось как откровенное мучение превратилось сначала в умную идеологию, а по итогу в самостоятельное решение для подготовки документации — Платформа «ГОСТ‑ОН».
С чего все началось
Знакомая картина: сидишь над документацией, копируешь в Word информацию из одного документа в другой, и понимаешь — завтра, скорее всего придется делать то же самое. И каждый раз, когда заказчик меняет требования, начинается ад: нужно обновить данные в десятке разных файлов, не потеряться в разных версиях, а еще и уследить за форматированием.
Думали - наймем техписа, и дело в шляпе
Сначала мы думали, что все решится, если у нас будет отдельно выделенный технический писатель. Но не тут то было. Из потенциального помощника технический писатель превращался в разражителя для аналитиков и разработчиков - понимание системы и прикладного контекста низкое, в лучшем случае решалась задача форматирования текста в Word, нежели качественное сутевое описание документов. Даже пробовали двух техписов держать, но это ли возвело в квадрат хаос коммуникации. В итоге либо главный аналитик или руководитель проекта в конце рабочего дня брали на себя подписку на мучение с документами.
Начало экспериментов - Confluence, макросы Word, Google Docs, MarkDown
Очевидно, что требовалось новое решение, которое бы сразу решало несколько задач:
синхронизация версией документой в облаке, чтобы не путаться в правках
преднастройка стилей форматирования документа
как-то уйти от копипаста или хотя бы сделать так, чтобы точно знать - где что надо поменять в случае изменения требований от заказчика.
Устроили всесоюзные смотрины основных продуктов и пришли к таким результатам:
Параметр | Word c макросами | Confluence | Google Docs |
Синхронизация версия | Не решает. WordOnline,когда еще был в России, как-то пытался решить задачу, но сейчас совсем тупиковая ветвь | Решается, версионирования по пользователям тоже работает | Лучший вариант - полный синхрон, управление правами |
Преднастройка стилей | Лучший вариант | По умолчанию не решается. Отдельными костылями решалось, но не настолько продвинуто как требует ГОСТ (рамки, тонкости выравнивания тексты, колонтитуты и т.д.) | Сложные элементы форматирования "слетают" при конвертации в Word. Заказчика всегда просил Word смотреть. |
Уход от копипаста | Функционал "полей" частично решал задачу, но UI не позволяет держать общую рамку и связь полей по всем документами | Макрос Include Page может решать эту задачу, но рушит на сложных элементах: мультиатрибутивные элементы описания и др. | Нет встроенного механизма переиспользования контента. |
Вердикт | Лучший вариант из плохих альтернатив | Можно было бы использовать, если бы не нюансы оформления документов по ГОСТ | Если документов мало и форматирование не критично - можно рассмотреть |
По итогу игры в «Голос» с каждым известным продуктом на рынке поняли, что полностью нашу хотелки не покрываются. Были большие надежды на Confluence, так как база знаний проектов уже там велось, но увы.
Думали пойти в эксперимент с MarkDown на VS Code, но к этому моменту уже было понятно, что надо делать что-то под себя кастомное. И вопрос был не столько в технической реализации, сколько в подходе к описанию документов.
Умная идеология - Каждый элемент описания ПО является информационной сущностью
Мы пришли к принципу переменных. Каждый элемент описания является информационным объектом
1. Атомарные поля
Простые поля типа «название системы», «заказчик», «исполнитель»
2. Списки
Плоские и вложенные перечисления. Например, «Внешние ИС, с которыми взаимодействует система» или «Документы-основания для разработки».
3. Изображения
Схемы, скриншоты, диаграммы. Скажем, «Компонентная схема», «Структурная схема» или отдельная папка - «Скриншоты для руководства администратора».
4. Объекты
Самый сложный тип переменных — сложные сущности с множеством атрибутов. Например, «Модуль» с вложенными «Функциями», которые связаны с «Экранными формами».
Вскоре под эту парадигму стали придумывать способы хранения и работы с этими сущностями. Проект шел под кодовым наименованием "ГОСТ-ОН". Так в итоге и назвали продукт.
Рождение ГОСТ-ОНа
В итоге мы пришли к некой форме IDE работы с документами. Но мы пошли дальше классического Docs-as-Code. Мы взяли привычный всем MarkDown, добавили мощный Python-ный шаблонизатор Jinja2, который бы работал с переменными и создали генератор документов, который позволяет учесть специфику российских ГОСТов и при этом сохранить гибкость для учета особых требований, возникающих на каждом проекте.
В итоге у нас родился триптих-вид рабочего места:
слева - панель переменные
по середине - основная рабочая зона с MD-редаткором, поддерживающим синатксис шаблонизации текста на базе Jinja2 (что это такое - лучше ознакомиться отдельно в руководстве)
справа - HTML-превью документа с возможностью экспорта в DOCX, PDF, HTML, MD.
Что принципиально поменялось
Время на форматирование практически сведено к нулю
В Платформе сразу живут правильные стили Word для каждого типа документа по ГОСТ. Хотите сменить Times New Roman на GOST Type A по ГОСТ 2 – делаем в один клик. Хочшеь с рамкой, хочешь без - все тоже настраивается.
Единый источники правды - хранятся не документы, а описания
Все описательные сущности хранятся по полочкам в базе даных. Каждый документ через синтаксис подтягивает нужные описания к конкретному документу. Документ генерируется по запросу пользователя в нужном форматировании.
Полное наименование системы: {{ full_is_name }}
Краткое наименование системы: {{ short_is_name }}
Исполнитель: {{ developer }}
И самый кайф: поменял один раз описание, это сразу транслируется на все документы, содержащие это описание.
У документации есть своя архитектура
Между сложными объектами можно делать иерархические и горизонтальные связи. За счет этого можно формировать сложные вложенные циклы, описывающие целые разделы технического задания.
Лучшие кейсы
Несколько житейских примеров из практики
Заказчик попросил поменять регистрационный номер ИС
Это такая особенность нумерации документов и их версий по ГОСТ 34.201.
Раньше: меняем колонтитутлы и титульные листы по ВСЕХ документах.
Стало: поменяли описание переменной {{ reg_number }} - все документы актуализированы.
Заказчик попросил поменять формат описания 146 методик испытаний ПО
ПМИ всегда одна из трудоемких задач для документации на систему, тем более что формат описания проверок всегда исходит от практики заказчика - ГОСТ жестко не регламентирует.
Раньше: 95% времени уходит на переформатирование таблиц в Word, нежели на проверку методик и их выпноление.
Стало: изменение 5 строк в редакторе для изменения вложенного цикла.
Что-то на будущее
Надеюсь, заметка была полезна. Есть еще много аспектов, которые возможно смогу раскрыть в будущем:
формы слов (падежи)
маленькие прелести (автонумерация рисунков и таблиц)
ИИ-агент
совместный режим и режим ревью
интеграция с облачным хранилищем файлов
перевод документации из ГОСТ в интерактивную веб-версию
Буду рад любой обратной связи!
