Недавно передо мной возникла задача написать документацию для большого проекта с довольно сложной структурой.

Сама по себе документация сегодня уже не кажется такой сложной задачей, как раньше. С помощью AI можно достаточно быстро разобраться даже в большом проекте. Главное — правильно сформулировать, что именно мы хотим получить, продумать структуру документации и дать AI необходимый контекст.

Но здесь возникает другая проблема.

Сложную архитектуру не всегда удобно описывать только текстом.

Как говорится, лучше один раз увидеть, чем сто раз прочитать.

Особенно это заметно, когда речь идёт о компонентах со множеством зависимостей, большим количеством связей или достаточно сложным процессом выполнения.

Как нарисовать схему?

Самый простой вариант — обычный ASCII:

User
|
v
Controller
|
v
Service
| \
|  v
| Repository
v
Queue
|
v
Worker

Работает. Для небольшой схемы вполне достаточно.

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

Другой вариант — воспользоваться графическим редактором и нарисовать нормальную диаграмму.

Получится гораздо нагляднее: блоки, стрелки, цвета, разные типы элементов.

Проблема начинается позже — такую диаграмму нужно поддерживать.

Изменился проект, появилась новая зависимость или компонент — нужно снова открывать графический редактор, добавлять элементы, двигать их, поправлять стрелки и сохранять новую версию.

Через некоторое время диаграмма легко начинает жить отдельной жизнью и перестаёт соответствовать реальному состоянию проекта.

И вот здесь я для себя открыл довольно интересный инструмент — Mermaid.js.

Mermaid — диаграммы из текста

Идея Mermaid довольно простая: вместо того чтобы рисовать диаграмму мышкой, мы описываем её обычным текстом.

Например:

flowchart TD
    User --> Controller
    Controller --> Service
    Service --> Repository
    Service --> Queue
    Queue --> Worker

Mermaid на основе этого описания строит диаграмму.

И главное — для изменения схемы не нужно ничего перерисовывать.

Например, в проекте появился Cache:

flowchart TD
    User --> Controller
    Controller --> Service
    Service --> Repository
    Service --> Queue
    Service --> Cache
    Queue --> Worker

Добавили одну строку — и схема изменилась.

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

Mermaid умеет не только блок-схемы

Mermaid — это не просто генератор flowchart. Он поддерживает достаточно много разных типов диаграмм.

Например:

flowchart;
sequence diagram;
class diagram;
state diagram;
ER diagram;
Git graph;
архитектурные диаграммы и другие.

Например, sequence diagram:

sequenceDiagram
    User->>API: Request
    API->>Service: Process request
    Service->>Database: Query
    Database-->>Service: Data
    Service-->>API: Result
    API-->>User: Response

Или простая диаграмма состояний:

stateDiagram-v2
    [*] --> Draft
    Draft --> Published
    Published --> Archived
    Archived --> [*]

То есть одним инструментом можно описывать не только структуру системы, но и процессы, последовательность действий и состояния объектов.

А причём здесь AI?

На мой взгляд, именно здесь Mermaid становится особенно интересным.

Поскольку диаграмма описывается текстом, её очень удобно генерировать с помощью AI.

Мне необязательно самому вспоминать синтаксис Mermaid и вручную описывать большую схему. Можно дать AI описание архитектуры или конкретного процесса и попросить:

Создай Mermaid sequence diagram, показывающую взаимодействие этих компонентов.

В результате получаем готовый код, который можно проверить, немного поправить и добавить в документацию.

Получается довольно простой процесс:

Проект
   ↓
AI анализирует структуру
   ↓
AI генерирует Mermaid
   ↓
Разработчик проверяет и корректирует
   ↓
Диаграмма становится частью документации

При этом я бы всё-таки не полагался на AI без проверки. Сгенерированная схема может выглядеть вполне убедительно, но при этом содержать неправильную связь или пропущенный компонент. Поэтому AI здесь хорошо подходит именно для быстрого создания первого варианта.

Главное преимущество — диаграмма становится кодом

Для меня это, пожалуй, самое важное преимущество Mermaid.

Диаграмма — это обычный текст, который можно хранить в Markdown вместе с остальной документацией.

А значит, Git прекрасно понимает её изменения.

Например, в diff можно увидеть:

Service --> Repository
Service --> Queue
+Service --> Cache

Сразу понятно, что именно изменилось в архитектуре.

Можно делать commit, смотреть diff, проводить code review, откатывать изменения и хранить всю историю.

И если архитектура проекта изменилась, достаточно изменить несколько строк Mermaid-кода.

Не нужно открывать графический редактор и заново раскладывать элементы по схеме.

Где это можно использовать?

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

Например, документация может находиться в Markdown-файле:

## Order processing

The order is processed through the following components:
 
```mermaid
flowchart LR
    API --> OrderService
    OrderService --> Payment
    OrderService --> Queue
    Queue --> Worker
```

В результате описание процесса и сама схема находятся в одном месте и могут изменяться вместе с кодом.

Mermaid также поддерживается популярными инструментами разработки и документации.

Например, GitHub поддерживает Mermaid нативно. Для PhpStorm существует отдельный плагин, а для Bitbucket также есть поддержка Mermaid.

Поэтому он особенно удобен для команд, которые хранят документацию непосредственно в репозитории.

В итоге

Для меня Mermaid оказался довольно простым, но полезным инструментом.

Мне кажется, при написании документации для сложных проектов полезно показывать не только что делает компонент, но и как он связан с другими компонентами и как проходит процесс выполнения.

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

И в сочетании с AI это получается довольно удобный инструмент для разработчика.