Docs as Code — это просто?

Всем привет, меня зовут Александр Мачулин, я сооснователь Gramax. Хочу с вами обсудить свой опыт использования подхода Docs as Code в повседневной работе в продуктовой и заказной разработке. Ключевой вопрос — просто ли это?

- Нет, это сложно.

Шутки кончились, перейдем к делу.

Недавно мы начали ходить на митапы и конференции для технических писателей и аналитиков, где сейчас начинает все больше обсуждаться Docs as Code, его преимущества, с чего начать изучение основ Git и т.д.

Тем хорошая и правильная, но есть несколько моментов, которые хотелось бы обсудить.

Как мы сами пришли к Docs as Code

Шел 2021 год, мы разрабатываем аналитические системы для Pharma и FMCG-производителей и наш технический директор Андрей решил наладить процесс ведения документации. Предложил вести всю информацию в Git и сделал простой static site generator. Полгода-год я работал с Markdown, Gitlab и даже не знал о существовании подхода Docs as Code, но что я точно знал:

  • Не хочу думать о командах в Git, в особенности о cherry-pick и revert, ну и других.

  • Каждый конфликт для меня боль, т.к. нет интуитивно понятного UI решения конфликтов. И я пишу в VSCode, а самый удобный для меня решатель конфликтов был в GitLab.

  • Я не понимаю ошибки Git. Нашел свою реакцию при очередной ошибке:

    Андрей, я капец как не хочу лезть в эти ветки.
    Мне проще сейчас все статьи в dropbox.paper скопировать и сказать команде “давайте там писать”.

  • Команда аналитиков и поддержки, стиснув, зубы пытается в Docs as Code, но тоже молча страдает от вышеперечисленных пунктов. Сначала пытался всем объяснить как удобно и легко создать, а потом смержить ветку (какой же лицемер). Спустя время успехом считали коммит сразу в мастер.

Мой бэкграунд, если что

Я позиционирую себя как аналитик с сильной технической частью. Много писал на SQL, Python, VB. Работал больше с Mercurial. Писал код в рамках проектов внедрения вместе с разработчиками, чтобы быстрее запустить в прод. Но закончил полностью этим заниматься за 2 года до событий в повествовании. И навык растерял.

Что нужно, чтобы Docs as Code работал

Человек привыкает ко всему, вот и я привык к лучшим инженерным практикам. Но проблемы на этом не закончились. Чтобы Docs as Code работал в вашей компании, вам нужно использовать и интегрировать 5 систем:

  1. Язык разметки и редактор. Допустим, пишем в VSCode в Markdown. Все просто, но за отдельную систему посчитаем.

  2. Markdown превью. По хорошему он нам нужен, чтобы видеть проблемы с разметкой. Проблема только в том, что плагины VSCode не интегрированы с нашим или любым другим static site generator.

  3. GitLab или GitHub. Я человек простой, вижу мерж реквест — иду в GitLab.

  4. Static site generator. Его необходимо подключить к Git-хранилищу и настроить CI/CD, чтобы при публикации изменений они пересобирали сайт. Изначально у нас не было CI/CD и все забывали нажать кнопку обновить на сайте с базой знаний, и контент часто был неактуальным.

  5. Диаграммы. Мы создавали профессиональные диаграммы в PlantUML, Draw.io, Mermaid и уныло складывали их картинками в Git.

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

Плюс добавлю пару важных вопросов от наших аналитиков:

  • А как делиться ссылками с внешними заказчиками?
    Т.е. мы должны иметь такую ссылку, по который заказчик может перейти, а любой человек из интернета без ссылки на портал с документацией попасть не должен.

  • Как узнавать об изменениях в базе знаний?
    Если что-то поменял, то надо идти в мессенджер, почту или таск-трекер и там всех уведомлять.

Почему мы начали разрабатывать свой продукт для Docs as Code

После длительного использования подхода я хотел бы выделить плюсы у Docs as Code, но для меня их совсем не было. Мы продолжали работать в таком ключе, только потому что у нас был вижн, что этот подход реально рабочий, но только в совокупности с автоматизацией и с хорошим пользовательским интерфейсом.

Поэтому, устав от моего нытья, в лаборатории ics-it команда ведущих инженеров трудилась днями и ночами, чтобы создать чудо. И чудо получилось, мы развили наш продукт — Gramax. Это WYSIWYG-редактор и понятный интерфейс к Git, который сохраняет все преимущества Docs as Code, но убирает барьеры для тех, кто не живет в терминале.

Зачем я вам об этом рассказываю

Мы решили свои проблемы, теперь их можете решить и вы.

Нетехнические специалисты работают как в привычном текстовом инструменте. Под капотом все равно происходят коммиты, слияния веток. Конфликты решаются через понятный UI. Превью совпадает с финальным результатом. Условный CI/CD настроен из коробки.

При этом Gramax не закрывает путь для тех, кто хочет работать с Markdown напрямую, через IDE или консоль — все это по-прежнему доступно.