Кто мы и чем занимаемся
Меня зовут Александр Курашов, и я работаю бизнес-аналитиком и архитектором в компании NAUKA.
NAUKA – одна из крупнейших (входим в ТОП-30 по версии TAdviser за 2024 год) ИТ-компаний России, занимающаяся разработкой, внедрением и сопровождением решений для предприятий нефтегазовой отрасли. У компании давняя история, в ней работает более 300 человек.
Один из наших знаковых проектов – разработка Платформы, объединяющей различные продукты компании в единую экосистему решений. А наша команда работает над ядровой частью Платформы– разрабатывает фреймворк, НСИ и сервисы, которые мы поставляем нашим коллегами – прикладникам, которые, в свою очередь, разрабатывают на их основе конечные приложения.
Наш подход к документации
Поскольку в нашей компании идет довольное большое количество разнообразных проектов (причем, не все они платформенные, не все – ERP и т. д.), то исторически сложилось так, что нет единого подхода к документации по проектам – фактически, каждый руководитель проекта самостоятельно определяет объем, состав и глубину проработки документации.
Читатель может сходу выкрикнуть слово «бардак!», но на самом-то деле, опытный аналитик, поработавший на большом количестве проектов, знает, что не стоит бездумно следовать какому-то единому шаблону – нужно адаптировать и экономить на исключении лишнего.
Мы ограничим область этой статьи той документацией, которой занимаются аналитики и архитекторы только на нашем проекте – Платформенного ядра ERP.
С самого начала проекта Платформы мы договорились, что документация обязательно должна быть (не очень-то оригинально, правда?). И вот по каким причинам:
Мы обязаны описать доменную область наших НСИ и платформенных сервисов, поскольку это - предмет поставки нашим коллегам, ведущим разработку прикладных приложений: мы даем им описанный фреймворк с НСИ, которым они обязаны пользоваться. Платформенные приложения должны выглядеть единообразно и полагаться на единую, хорошо структурированную НСИ.
Санировать «фактор кирпича» – часто бывает так, что уже через несколько месяцев сам аналитик, даже если он все еще работает на том же проекте, не в состоянии вспомнить, что конкретно он передал разработчикам, а главное – зачем. А ведь люди еще и уходят, и уходят внезапно! Наверно, у многих из вас были случаи, когда, «получив в наследство» сервис от смежной команды вы опрашивали «оставшихся в живых» разработчиков и аналитиков и потом «задним числом» оформляли документацию.
Ускорение онбординга. Сейчас, поскольку все наши крупные сервисы и системы описаны хотя бы на уровне Vision, то при вовлечении нового аналитика или разработчика мы даем ему пачку ссылок для чтения – и он возвращается к нам через пару дней уже с пониманием наших процессов и осмысленными вопросами. А в противном случае мы бы потратили минимум 4–5 человеко-дней очень дорогого времени лидов просто на то, чтобы «проговорить» структуру Платформы.
Наш проект в этом смысле несколько особенный – у него нет внешних заказчи��ов. Но они есть у наших прикладных проектов, которые используют Платформу! И поэтому у них добавляется четвертый – важнейший пункт – предоставить документацию внешним потребителям в строгом соответствии с форматом, определенном в договоре – и мы им в этом помогаем, предоставляя ее ядерную часть.
Какую методологию выбрать?
С самого начала встал вопрос – какую методологию взять за основу, какой фреймворк и какие шаблоны артефактов? Нашей задачей было вписаться в следующие требования:
На проекте есть 2,5 аналитика (в т. ч. 1 лид), которые «обслуживают» 7–8 разработчиков (в т. ч. 2 лида), 1 техписа и 1 тестировщика. Это, надо сказать, сразу же задает крайне жесткие требования к объему документации – «воду» лить некогда. В среднем за 4 года работы на проекте соотношение затрат аналитики к разработке редко превышало 20–25%.
Наш шаблон документирования должен был быть близок к «шаблону здравого смысла» - и не задавать требований к нанимаемым аналитикам на уровне сеньора-помидора. Смешно было бы писать: «Нам нужен 20-летний аналитик с 30-летним опытом TOGAF». Хотя, признаемся, мы анализировали шаблоны документов для 10-ой версии TOGAF, по итогу, почерпнув некоторые вещи для документов верхнего уровня. Вывод – наши результирующие документы должны быть предельно просты.
Методически мы постарались опереться на принципы технического документирования, скомпонованные Gernot Starke, автором известного шаб��она arc42, в довольно компактную диаграмму. Не будем ее пересказывать, лишь отметим, что в своем подходе мы соблюли их почти все (отмечены, как Req-X на диаграмме)
Также мы закрепили на нашем проекте принцип Documentation First – мы не ведем разработку без предварительно оформленной бизнес-документации.
Мы шли итерационно, но с самого начала мы зафиксировали, что:
Не будем «в лоб» применять крупный фреймворк Enterprise Architecture типа TOGAF (в т. ч. Archimate), Zachman
Возьмем только минимальный набор артефактов «для выживания» из всего их сонма – довольно большую помощь в осмыслении этого оказала сводная диаграмма Enterprise Architecture Artifacts on a Page Святослава Котусева
В итоге мы остановились на бизнес-документации в составе:
ADR (Architecture decision record)
Vision (Документ о концепции и границах)
SRS (Software requirements specification - Спецификация требований к ПО) или (!!!) ТП (Технический проект)
И прочих документах:
Стандарты и методология
Техническая документация разработчика
Пользовательские инструкции
Архитектурная документация ландшафтов в C4 (только начинаем и не будем описывать эти документы в настоящей статье)
Перед тем, как рассмотреть эти документы более подробно немного расскажем о бизнес-процессе документирования.
Процесс документирования и инструментарий
Бизнес-документацию (ADR, Vision, SRS/ТП) разрабатывают аналитики или архитектор (лид). Пользовательские инструкции пишут техписы, основываясь на ТП.
В качестве конечного редактора мы используем проверенные IntelliJ IDEA Community Edition или VS Code (на выбор аналитика).
Три «технических» кита, на которых мы стоим – это:
Markdown
GitLab
MkDocs
Текст документации – это почти всегда markdown, который размещается в нашем аналитическом репозитории GitLab. Отмечу, что аналитический репозиторий обслуживает не только наш проект Платформы, но и несколько прикладных проектов, пожелавших вести документацию в Git (некоторые проекты ведут документацию в xWiki).
Используется очень простая схема работы с ветками Git: когда аналитику необходимо разработать или уточнить документацию он «брэнчится» от main и создает документы в новой ветке. По готовности от выполняет Push и создает Merge Request со ссылками на документы.
Мы используем MR не только для контроля разработанной аналитики лидом, а в первую очередь для организации уведомлений и согласований. К нашему аналитическому репозиторию подключено более 150 человек (это члены всех Платформенных прикладных команд, архитектурный комитет и высшее руководство). А руководители прикладных проектов доводят до нас актуальные списки тех членов своих команд, которых мы обязаны уведомить в случае разработки документации.
В результате каждый (да – именно каждый !!!) MR содержит секцию упоминаний всех необходимых «интересующихся» и «согласующих» со сроком выдачи замечаний и предложений – обычно дискуссии с предложениями идут прямо в тредах этого MR - аналитик вносит при необходимости уточнения в документы и снова пушит в Git.
Важно, что, следуя принципу Documentation First, мы не передаем в разработку документацию без окончательного согласования MR (Approve) от внутренних заказчиков.
Конечно, в процессе возможны некоторые «завихрения», когда, например, тех.лиды, с которыми также согласовывается документация, вносят существенные корректировки по концепции решения – происходит возврат аналитику, пересогласование и т. д. Но в большинстве случаев все проходит довольно стандартно – мы намеренно решили не усложнять схему сложной статусн��й схемой с блокировками – достаточно контроля за хронологическим состоянием документации.
В итоге все завершается передачей в разработку и выполнением merge в main – обычно merge происходит, когда разработка уже идет или завершена – нередко разработчики находят мелкие неточности в документации (опечатки в SQL, алгоритмах и т. д.)
Merge в main сопровождается запуском pipeline в Git, который выполняет пересборку портала документации в MkDocs на корпоративном сайте. Общая схема бизнес-процесса выглядит так:
Обычно порталом документации пользуется руководство или конечные пользователи – опосредованно получающие запакованные сборки этого портала с включенными в них руководствами и пользовательскими инструкциями. Отметим, что MkDocs генерирует отличный интерфейс с навигацией и быстрым контекстным поиском.
Список плагинов, которые мы используем для его тонкой настройки, указан в файле настроек в репозитории. Поскольку MkDocs поддерживает кучу классных фишек типа миниатюр рисунков, инфоблоков и прочего, то наши техписы оформили гайд по оформлению любого документа в формате .md - аналитики теперь знают какие правила наполнения статей использовать для каждого элемента языка: заголовка, списка, блока кода, как оформить схему с миниатюрой и popup, как оформить таблицу с нужным форматированием и вкладку.
Отметим, что все описанное выш�� относится только к бизнес-документации и пользовательским инструкциям – техническую документацию разработчики пишут непосредственно «рядом» с кодом, объединяя ее в сводный Git-репозиторий, а затем в отдельный «технический» портал MkDocs – вероятно, это тема для отдельной статьи с названием «Как собрать единый портал документации?» - но мы пока не готовы ее написать, поскольку сами находимся в процессе организации этого слияния.
Итак - мы осветили общий подход к процессу подготовки документации. Чтобы не превращать статью в ужасный лонгрид, дадим читателю передышку и перейдем к составу и деталям документации во второй части статьи.
