Всем привет, меня зовут Александр Мачулин, я сооснователь 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 команда ведущих инженеров тредулась днями и ночами, чтобы создать чудо. И чудо получилось, мы развили наш static site generator в полноценный WYSIWYG и понятный интерфейс к GitLab — Gramax.

Причём, Gramax не ограничивает в использовании Markdown, IDE и Git-команд в консоли. Но делает и тот, и другой подход к наполнению базы знаний удобным и бесшовным для того, кто пишет и для того, кто читает.

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

Мы сделали хорошее приложение и решили свои проблемы. Теперь с его помощью решить проблемы можете и вы. Использование абсолютно бесплатно, в ближайшие пару месяцев выложим исходный код в опенсурс.

Скачивайте приложение и участвуйте в популяризации подхода Docs as Code и лучших инженерных практик в продуктовой разработке — для этого вступайте в наш чат и рассказывайте о своих проблемах.