Доклад с FOSDEM 2023: How to draw your Kubernetes cluster the right way посвящён Kubernetes, но его советы по созданию диаграмм универсальны и актуальны по сей день. Если пропустили, вот первый пост о диаграммах.
Ключевые рекомендации по созданию диаграмм:
⚪️ Держи диаграммы в чистоте
Не перегружай диаграмму деталями. Вместо того, чтобы рисовать каждый под в Kubernetes-кластере, покажи только ключевые компоненты (ноды, сервисы, ingress).
⚪️ Используй абстракции: вместо 10 одинаковых элементов покажи один с подписью "x10".
⚪️ Используй стандартные нотации
Для архитектурных диаграмм применяй C4 Model (Context, Containers, Components, Code) или UML, чтобы твои диаграммы были понятны другим.
Для Kubernetes используй стандартные иконки (например, из официального набора Kubernetes Icons). Эта, казалось бы, мелочь, замерялась в исследовании по восприятию диаграмм и показала свою значимость.
⚪️ Добавляй контекст
Понимай, для кого предназначена диаграмма (разработчики, менеджеры, заказчики) и создавай ее с опорой на их потребности. Например, для менеджеров достаточно высокоуровневого обзора, а для инженеров — деталей.
Подписывай зависимости и потоки данных (например, стрелки между сервисами).
⚪️ Поддерживай актуальность
Храни диаграммы в репозитории вместе с кодом (например, в формате Mermaid или PlantUML), чтобы их можно было обновлять. Используй версионирование (Git), чтобы отслеживать изменения.
⚪️ Делай диаграммы читаемыми
Используй контрастные цвета (например, тёмный текст на светлом фоне). Избегай мелкого шрифта — текст должен быть читаемым даже при масштабировании. Группируй связанные элементы (например, рисуй рамки вокруг нод одного кластера).
Эти советы применимы не только к Kubernetes, но и к любым диаграммам: от процессов CI/CD до архитектуры микросервисов.
Лучший источник по созданию осмысленных и эффективных диаграмм, — «Модели общения» Джеки Рид. Книга (.epub на англ.) наполнена практическими рекомендациями по превращению сложных идей в осмысленные визуальные образы.
Пользуйтесь и делитесь с коллегами 🫡
@DevOpsKaz 😛