Кейс: Модернизация документации архитектуры с помощью VPasCode – Обзор продукта

Введение

Как технический руководитель, отвечающий за растущий набор микросервисов, наша инженерная команда была погружена в долг по документации. Мы использовали несколько инструментов: Visio для архитектуры высокого уровня, Lucidchart для быстрых схем и локальные установки PlantUML для схем баз данных. В результате: разорванные линии соединения, кошмары с системой контроля версий из-за бинарных файлов изображений и огромная проблема для новых разработчиков, которым нужно было настраивать локальную среду Java и Graphviz, чтобы просто посмотреть диаграмму.

Мы понимали, что нам нужно внедрить подход «диаграмма как код», но ранние тесты с существующими инструментами казались фрагментированными. Появляется VPasCode (Visual Paradigm как код). Позиционируется как платформа в браузере, с несколькими движками, преобразующая текст в диаграммы, с глубокой интеграцией ИИ, и обещает стать единым центром, который нам так не хватало.

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

Проблема: Почему нам нужна была смена

До внедрения VPasCode наша документационная рабочая процедура была нарушена.

1. Фрагментация среды: Разработчики, использующие PlantUML, постоянно сталкивались с проблемами «работает у меня», из-за несоответствия локальных зависимостей.

2. Переключение контекста: Нам приходилось покидать наши IDE и редакторы Markdown, чтобы использовать веб-инструменты с перетаскиванием, что нарушало наш поток работы.

3. Проблема «чёрного ящика» ИИ: Мы пробовали несколько генераторов диаграмм с ИИ, но когда ИИ ошибался или «исправлял» наш код, он делал это молча. Мы не могли отследить, что именно изменил ИИ, из-за чего сдерживали доверие к нему при работе с сложной корпоративной архитектурой.

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

Практический кейс: Наша рабочая процедура внедрения

Чтобы протестировать VPasCode, мы взяли на себя задачу документирования новой системы управления библиотечными активами. Ниже — точная рабочая процедура, которую наша команда использовала на платформе.

Шаг 1: Нулевая сложность настройки

Самым большим преимуществом стало отсутствие сложностей при настройке. Я поделился ссылкой на VPasCode с командой. Никакого программного обеспечения не нужно было устанавливать, не требовалось настраивать зависимости npm, не нужно было отлаживать локальные среды Java. Мы сразу оказались в пустой среде, сопоставимой с IDE.

Шаг 2: Использование гибкости многодвиговой платформы

В отличие от инструментов, привязывающих к одному синтаксису, VPasCode позволил нам использовать нужный инструмент для нужной задачи в одной и той же рабочей среде:

• Мы использовали PlantUML для создания строгих, объектно-ориентированных связей базы данных и иерархий классов для системы активов.

• Мы переключились на Mermaid.js чтобы быстро создать документацию в формате Markdown, ориентированную на пользователя, для последовательности заимствования книг.

Шаг 3: Создание черновиков с помощью ИИ

Вместо того чтобы писать каждый элемент с нуля, мы использовали встроенный помощник ИИ. Я задал чат-боту запрос: «Создайте систему библиотеки, где члены могут брать или бронировать книги, включая абстрактный класс Asset.» В течение нескольких секунд он сгенерировал очень точный блок базового синтаксиса. Затем мы вручную уточнили бизнес-логику, сэкономив около 30% времени на первоначальном чертеже.

Шаг 4: Предварительный просмотр в реальном времени и итерации

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

Обзор продукта: Прорывной функционал «Детали исправления ИИ»

Хотя поддержка нескольких движков и среда без настройки — это фантастически, функция, которая действительно заставила меня поверить — и причина, по которой я пишу этот обзор — это«Детали исправления ИИ» панель.

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

Усовершенствованный рабочий процесс в действии

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

1. Исправление: Когда я нажал «Исправить с помощью ИИ», движок мгновенно исправил мой синтаксис и отобразил диаграмму.
   

2. Уведомление: На верхней части экрана появилась элегантная строка уведомлений:«Диаграмма исправлена с помощью ИИ».

3. Раскрытие: Рядом с баннером находится кнопка«Просмотреть детали» открывает подробное всплывающее окно, в котором подробно описаны точные изменения.
   

Внутри диалогового окна «Детали исправления ИИ»

Окно разделено на две очень информативные секции:

• Верхняя часть (объяснение ИИ): Объяснение на простом английском языке от ИИ, подробно описывающее, какую именно синтаксическую ошибку он обнаружил (например, «Отсутствует открывающая скобка в строке 7») и как он подошел к решению.

• Нижняя часть (компонент сравнения кода): Точное сравнение кода в режиме рядом. Красные выделения обозначили поврежденные участки слева, а зеленые — четко выделили исправленный синтаксис справа.

Попробуйте сами

Вы можете протестировать это точное улучшение, используя приведенный ниже проблемный код PlantUML. Обратите внимание на отсутствующую открывающую скобку{на строкеабстрактный класс Assetстроке. Нажмите на ссылку, чтобы открыть VPasCode и наблюдать, как ИИ прозрачно исправляет ошибку.

@startuml
skinparam style strictuml
interface Printable {
  + print(): void
}
abstract class Asset 
  # id: String
  # name: String
  + {abstract} getValuation(): double
}
class Device extends Asset implements Printable {
  - ipAddress: String
  + print(): void
  + getValuation(): double
}
class Department {
  - deptId: String
  + assets: List
}
Department "1" *-- "0..*" Asset : manages >
@enduml

Редактировать PlantUML в VPasCode

Исправленная версия (исправление ИИ)

@startuml
skinparam style strictuml

interface Printable {
  + print(): void
}

abstract class Asset {
  # id: String
  # name: String
  + {abstract} getValuation(): double
}

class Device extends Asset implements Printable {
  - ipAddress: String
  + print(): void
  + getValuation(): double
}

class Department {
  - deptId: String
  + assets: List
}

Department "1" *-- "0..*" Asset : manages >
@enduml

Мое честное мнение о прозрачности ИИ

1. Абсолютное доверие:Разница в коде дает мне полное спокойствие. Это доказывает, что ИИ безопасно нацелен на точную синтаксическую ошибку, не внося произвольных изменений в мою базовую бизнес-логику.

2. Интерактивное обучение:Читая объяснения ИИ на простом языке и наблюдая визуальную разницу, платформа превращается из простого редактора в активный инструмент обучения, помогающий младшим разработчикам освоить тонкие нюансы синтаксиса PlantUML и Mermaid.

3. Легкая проверка изменений:Зная точно, что изменилось, я могу легко проверить внесенные изменения или вручную отменить конкретные решения, если исправление ИИ не соответствовало моему первоначальному архитектурному замыслу.

Итоговое мнение: Стоит ли VPasCode инвестиций?

После трех недель интенсивного использования VPasCode официально заменил наш фрагментированный стек диаграмм. Он успешно устраняет разрыв между рабочими процессами, ориентированными на разработчиков «сначала код», и визуальными требованиями корпоративной архитектуры. Устранение локальных зависимостей в сочетании с редактором уровня IDE делает его невероятно удобным инструментом для наших ежедневных стендапов и планирования спринтов.

Плюсы:

• Настоящий нулевой настройки, рабочее пространство в браузере.

• Бесшовный переключатель между PlantUML, Mermaid и Graphviz.

• Непревзойденная прозрачность ИИ с боковым сравнением кода и панелью объяснений.

• Интеграция с OpenDocs Pipeline для встраивания живых диаграмм в наши руководства команды.

Но есть нюанс:
Важно отметить, что хотя базовая песочница бесплатна для пробного использования, расширенный диалог исправления деталей ИИ и премиум-функции ИИ требуют премиум-учетной записи (например, Visual Paradigm Online Combo Edition или Visual Paradigm Desktop Professional Edition с действующим обслуживанием). Для профессиональной инженерной команды это оправданная стоимость с учетом экономии времени, но отдельные любители должны быть осведомлены о платном доступе к продвинутым инструментам ИИ.

Для команд, стремящихся модернизировать свою инженерную документацию, устранить усталость от перетаскивания и использовать ИИ, не жертвуя прозрачностью кода, VPasCode — это обязательно к пробе.

Попробуйте прямо сейчас по адресу: https://www.vpascode.com/

Ссылки и дополнительная литература

1. Обзор функций VPasCode: Официальный обзор функций единой платформы текст-в-диаграмму от Visual Paradigm.

2. Представляем VPasCode: Идеальная единая платформа текст-в-диаграмму: Заметки о выпуске и введение в рабочую среду VPasCode в браузере.

3. Полное руководство по VPasCode от Visual Paradigm: Полное руководство и гайд по освоению VPasCode.

4. VPasCode: Революция в инженерной документации с помощью диаграмм как кода: Обзор стороннего эксперта о том, как VPasCode трансформирует техническую документацию.

5. От запроса к шаблону: Освоение диаграмм классов UML с помощью ИИ: Руководство по использованию запросов ИИ для генерации диаграмм классов UML в VPasCode.

6. Революция в обслуживании диаграмм: Автоисправление ИИ: Обзор возможностей автоисправления синтаксиса и автоисправления ИИ в VPasCode.

7. Устранение языковых барьеров нативно с помощью перевода диаграмм ИИ в VPasCode: Обновление выпуска, посвященное новой функции многоязычного перевода меток диаграмм.

8. Освоение VPasCode: Идеальное руководство по диаграммам как коду с ИИ: Расширенное руководство, охватывающее поддержку нескольких движков, включая PlantUML, Mermaid и Graphviz.

9. Безупречная интеграция диаграммирования с документацией: интеграция OpenDocs: Обновление, описывающее интеграцию OpenDocs Pipeline для встраивания живых диаграмм.

10. Освоение вариантов использования: от концепции до реализации: Учебник по созданию диаграмм вариантов использования с использованием подхода диаграмм как кода.

11. Освоение моделирования вариантов использования с ИИ: руководство для начинающих: Дружелюбное для новичков руководство по сочетанию ИИ с PlantUML для моделирования вариантов использования.