Diagramm-as-code – удобно?

Раз уж начали говорить про документацию, давайте обсудим самое насущное. Что чаще всего делает аналитик? Правильно, рисует диаграммы. Но это полбеды. Диаграммы нужно править. И не один раз. Обычные рисовалки как draw.io требуют много времени на правки, и я полюбила подход, когда нужно писать код для создания диаграмм.

Что рисуем
flowcharts, sequence diagrams, class diagrams, entity relationship diagrams

Какие плюсы я увидела
➕ Простота внесения изменений
➕ Возможность совместной работы

Что мне не понравилось
Код обычно храним в репо, иногда мы так и делаем, но чаще всего диаграммы вставляются в документацию. Не все базы знаний имеют макросы, в которые в режиме редактирования пишешь код, а в режиме чтения видишь диаграмму. А это значит, исходник нужно тоже где-то хранить. Иногда я вставляю его прямо на страницу в виде скрываемого текста, а иногда храню отдельно. А это, как понимаете, не очень удобно и эстетично.


Какие инструменты рекомендую

🟤 Mermaid
простой и легкий инструмент, основанный на Markdown-подобном синтаксисе для создания различных типов диаграмм.

🔹 Поддерживает множество форматов вывода, таких как SVG, PNG и PDF.
🔹 Простота использования благодаря легкому синтаксису.
🔹 Может использоваться в паре с платформами вроде GitHub Pages, ReadTheDocs и MkDocs для автоматического отображения диаграмм.

Для visual studio Code требует отдельного плагина.

🟤 PlantUML
Мощный генератор UML-диаграмм, использующий собственный текстовый язык для построения классов, последовательности действий, компонентов и другой сложной архитектуры программного обеспечения.

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

PlantUML я использовала онлайн. Редакторов много, вот один из них https://editor.plantuml.com/


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