_
На одном из созвонов сообщества мы обсуждали инструменты для ведения проектной документации, частью которой являются и диаграммы. И вот вчера на 1-1 инженер поделился проблемой, что конечный автомат состояний апи не задокументирован. Он начал чертить диаграмму, закопался в сложности и хочет отложить это дело.
Надев кепку коуча, я его попросил не откладывать. Диаграмма — дело хорошее, нам скоро в этот проект все равно залазить с другими целями. Для него это будет хороший кейс демонстрации ответственности.
Я его попросил следовать простым правилам:
1. Начни с малого. Задокументируй то, что понял и изобрази остаток системы, как черный ящик
2. Опубликуй и сделай презентацию
3. Убедись, что диаграмму легко обновить
4. Нацелься на то, что ты ее таки закончишь в обозримой перспективе
Только с диаграммами есть проблема: их невозможно обновлять. Это одна из причин, почему они устаревают. Даже если дать ссылку на Lucid Chart или другой инструмент, то всегда возникнут проблемы с доступом к инструменту, версиями, платными рабочими местами и тд.
Есть выход. Можно использовать инструменты, которые позволяют преобразовать текст в диаграмму. Например, https://d2lang.com/
С таким подходом очень просто исправить опечатку или добавить связь. Движок сам нарисует. Меньше думаешь — легче живешь. Да, и хранить можно прямо в гите.
Вот для примера диаграмма, как я пишу посты:
title: Как Дима пишет посты {
near: top-center
shape: text
style: {
font-size: 29
bold: true
underline: true
}
}
Случай на работе -> Notion
Ситуация на созвоне -> Notion
Notion -> Проработка информации -> Notion
direction: right
Notion -> ✨ Магия -> Пост