Документация на проекте

На одном из созвонов сообщества мы обсуждали инструменты для ведения проектной документации, частью которой являются и диаграммы. И вот вчера на 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 -> ✨ Магия -> Пост

Вот, что из этого генерирует библиотека:

Альтернатив у d2 много, даже целый сайт есть, где можно удобно все потрогать: https://text-to-diagram.com/. В комментариях в телеграме люди делились своими инструментами. Используют, в основном plantUML и Mermaid. Кто-то использует draw.io.

У подхода с автогенерацией тоже есть проблемы. Большие диаграмы могут получиться нечитаемыми. Или если выгружать в растровый формат, то приблизить мелкий текст уже не получится. Поэтому, конечно, нужно выбирать инструмент под задачу. Но теперь у вас есть еще один инструмент на выбор.