Как перестать рисовать схемы в Paint и полюбить документацию

Знакомая ситуация: вы полдня рисовали красивую архитектурную схему в Visio или Lucidchart, вставили её скриншот в Wiki проекта, а через неделю API изменился? Теперь нужно искать исходник, перерисовывать стрелочки, снова делать скриншот... В итоге документация «протухает», потому что обновлять графику — это отдельный вид боли.

Но что, если я скажу, что диаграммы можно писать обычным текстом, прямо как код? Познакомьтесь с Mermaid — инструментом, который превращает ваш Markdown-подобный текст в стильные и понятные схемы.

Что такое Mermaid и зачем он вам нужен?

Mermaid — это JavaScript-библиотека, которая берет текстовое описание и рендерит его в SVG-графику. Главная идея проекта — победить «Doc-Rot» (гниение документации). Когда схема — это текст, её легко хранить в Git, легко править и, что самое важное, легко автоматизировать её создание.

В моей практике Mermaid стал спасением для команд, которые ведут документацию в GitHub или GitLab. Эти платформы поддерживают Mermaid «из коробки», так что ваши схемы будут отображаться прямо в README.md без лишних телодвижений.

Как это работает на практике?

Давайте посмотрим на несколько примеров. Синтаксис настолько интуитивен, что его можно освоить за 5 минут.

1. Простые Flowcharts (Блок-схемы)

Вместо того чтобы двигать блоки мышкой, вы просто описываете связи:

flowchart LR
    A[Клиент] -->|Запрос| B{Авторизован?}
    B -- Да --> C[Доступ к API]
    B -- Нет --> D[Ошибка 403]

Один взгляд на код — и вы понимаете логику. Изменилось условие? Просто поменяйте текст в фигурных скобках.

2. Sequence Diagrams (Диаграммы последовательности)

Это, пожалуй, самый востребованный тип диаграмм у бэкенд-разработчиков. Описать взаимодействие микросервисов теперь проще простого:

sequenceDiagram
    Alice->>John: Привет, Джон! Как дела?
    loop Проверка здоровья
        John->>John: Борьба с ипохондрией
    end
    Note right of John: Рациональные мысли!
    John-->>Alice: Все отлично!

3. Диаграммы классов и состояний

Для тех, кто проектирует сложную архитектуру или работает с конечными автоматами, Mermaid предлагает строгий и лаконичный синтаксис. Вы можете описать методы, атрибуты и отношения наследования, не отрывая рук от клавиатуры.

classDiagram
    Class01 <|-- AveryLongClass : Наследование
    class Class10 {
      <<service>>
      int id
      size()
    }

Почему это круче обычных графических редакторов?

1. Версионность: Схемы лежат в Git. Вы видите diff — кто, когда и какую стрелочку изменил.
2. Единообразие: Все схемы в проекте выглядят в одном стиле. Никаких «вырвиглазных» градиентов от коллеги-дизайнера.
3. Интеграции: Mermaid поддерживается везде — от VS Code и Obsidian до Notion и Jira.
4. Живой редактор: У проекта есть Live Editor, где можно набросать схему и сразу увидеть результат.

Техническая «начинка»

Проект написан на TypeScript и под капотом использует мощь библиотеки D3.js для отрисовки. Интересно, что разработчики очень серьезно относятся к безопасности. Поскольку Mermaid рендерит пользовательский текст, существует риск XSS-атак. Чтобы этого избежать, в библиотеке реализован режим песочницы (sandboxed iframe), который блокирует выполнение вредоносных скриптов, встроенных в описание диаграммы.

Кстати, Mermaid — это не просто библиотека для браузера. У него есть CLI-интерфейс, позволяющий генерировать изображения в процессе CI/CD. Представьте: вы пушите код, а ваш пайплайн автоматически обновляет схемы в документации на основе актуальных данных.

Кому точно стоит попробовать?

• Системным аналитикам: Чтобы быстро фиксировать требования.
• Архитекторам: Для визуализации связей между сервисами.
• Техписам: Чтобы документация всегда соответствовала реальности.
• Разработчикам: Просто чтобы не тратить время на рисование в сторонних сервисах.

Mermaid — это тот редкий случай, когда инструмент действительно упрощает жизнь, а не добавляет новых хлопот. Он превращает документирование из рутины в процесс, похожий на написание кода. Если вы еще не используете его в своих проектах — самое время начать с README.md вашего текущего репозитория.

Попробуйте зайти в Live Editor, скопируйте туда любой пример из этой статьи и попробуйте что-то изменить. Уверен, вам понравится этот уровень контроля над графикой!