Аналитики, использующие PlantUML, Miro, Draw.io, Visio, Structurizer и прочее, забывают что знания в диаграммах - всё равно что код в скриншотах.

Знания должны храниться в виде взаимосвязанных элементов Модели, а диаграммы должны быть лишь их Проекциями. Именно это позволяет системе ArchiVision значительно эффективнее хранить знания об ИТ системах чем все вышеназванные сервисы. При этом, генерируемые ею диаграммы живые, интерактивные и редактируемые. Система также поддерживает горячие клавиши для эффективной работы с моделью и диаграммами. Горячие клавиши позволяют рисовать быстрее, чем большинство перечисленных сервисов, тем более чем делать описания в PlantUML, Structurizer и их аналогах.

⚡ Ключевые отличия:

• 🤔 в названных выше инструментах вы редактируете диаграммы;
• 🎯 в ArchiVision вы работаете с моделью, а диаграммы - это её визуальная проекция, через которую тоже можно развивать модель.

🔄 За счет этого:

• 🧠 модель становится единственным источником истины;
• 🧱 диаграммы перестают быть хрупким артефактом;
• 🧩 структура модели позволяет устранять разночтения, дублирование и рассинхронизацию;
• ✅ система способна контролировать ввод и проверять полноту данных;
• 🧼 архитектура перестаёт расползаться по версиям и интерпретациям;
• ⌨️ навигация и горячие клавиши — это часть работы с моделью, а не удобство интерфейса.

🎥 Видео ниже - пример того, как сочетание модели, интерактивной диаграммы и горячих клавиш меняет сам процесс проектирования.

Здравствуйте!

Сегодня мы поговорим о важной теме - о документировании ИТ-решений и ИТ-инфраструктуры, а также о выборе инструментов её описания.

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

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

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

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

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

Первый подход - внедрение промышленных инструментов.​

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

• Высокий уровень детализации и мощные возможности моделирования.
• Возможности автоматизации процессов документирования.
• Полный контроль над вводимыми в систему данными.
• Поддержка отчетности и стандартизированных методологий.
• Возможность управления версиями.
• Возможности автоматизировать внутренние процессы.
• Возможность миграции на альтернативные решения.

• Высокая стоимость владения (лицензии, консалтинг, поддержка, доработки, автоматизация).
• Процесс внедрения, который может затянуться и который не всегда легко организовать.
• Зависимость от вендора и его политик.
• Зависимость от команды узкоспециализированных специалистов.
• Санкционные риски.
• Финансовые риски - в период нестабильности может быть принято решение об отказе в финансировании.

Второй подход - использование облачных инструментов для описания ИТ-архитектуры.​

Облачные решения привлекательны благодаря своей доступности и низким затратам на использование, что делает их особенно удобными для организаций с ограниченным бюджетом. Они, как правило, обладают интуитивно понятным интерфейсом и готовы к работе сразу после подключения. Это позволяет пользователям быстро освоить инструмент с минимальными затратами на обучение и внедрение. Однако у таких решений есть и ограничения. Они часто имеют ограниченные возможности кастомизации, а поставщики сервисов ориентируются на массовый рынок, развивая функционал, востребованный большинством клиентов. В результате компании с особыми требованиями могут столкнуться с нехваткой нужных возможностей. Кроме того, переход на другие системы может вызвать сложности с миграцией данных, а риск потери контроля над данными остается высоким. Большинство облачных провайдеров предлагают свои услуги «как есть», без гарантий безопасности и доступности данных. В их соглашениях четко указано, что ответственность за возможные утраты или утечки информации не несется. Для финансовых организаций и государственных структур, где требования к защите данных особенно высоки, такой подход, как правило, неприемлем.

• Быстрое внедрение и интуитивный интерфейс.
• Низкие первоначальные затраты.
• Доступность из любой точки мира.

• Ограниченные возможности кастомизации.
• Ограниченные возможности по управлению доступом.
• Ограниченные возможности по автоматизации.
• Зависимость от провайдера и возможные сложности с миграцией данных.
• Отсутствие гарантий безопасности и доступности данных.
• Возможные проблемы с миграцией данных на другие платформы.
• Возможные ограничения на использование таких инструментов политиками компаний.
• Ограниченные аналитические функций.

Третий подход - различные графические редакторы с возможностью рисования диаграмм.​

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

• Простота использования на первых этапах.
• Быстрый старт без необходимости сложных настроек.

• Высокие затраты на поддержание актуальности и непротиворечивости документации.
• Ограниченные возможности по управлению доступом.
• Ограниченные возможности по кастомизации или их полное отсутствие.
• Ограниченные возможности по автоматизации или их полное отсутствие.
• Отсутствие поддержки версионирования.
• Отсутствие автоматического контроля за стилистикой оформления документации.
• Возможные проблемы с миграцией на другие платформы.
• Отсутствие гарантий безопасности и доступности данных.
• Отсутствие возможности наполнять элементы данными, необходимыми для анализа.
• Отсутствие востребованных аналитических функций.

Этот вариант сильно подвержен человеческому фактору, что со временем может привести к снижению качества документации.

Четвертый подход - свободнораспространяемые инструменты не требующие лицензирования.​

Рассмотрим один из ярких представителей таких инструментов - PluntUML. Это бесплатная расширяемая библиотека, которая позволяет визуализировать текстовые описания, превращая их в привлекательные диаграммы. Если рассматривать отдельно нарисованную диаграмму, когда все элементы описаны в одном файле, то данный инструмент вполне оправдывает его столь широкое распространение. Он отлично подходит для быстрого прототипирования ИТ-решений, однако он не реализовывает и даже не предназначен для покрытия тех требований, которые позволили бы полноценно управлять документацией в компании.

• Бесплатность и возможность кастомизации.
• Простота использования на первых этапах.
• Поддержка текстового описания диаграмм.

• Высокие затраты на поддержание актуальности и непротиворечивости документации.
• Ограниченные возможности по управлению доступом.
• Ограниченные возможности по автоматизации или их полное отсутствие.
• Отсутствие поддержки версионирования.
• Отсутствие возможности наполнять элементы данными, необходимыми для анализа.
• Отсутствие востребованных аналитических функций.

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

Пятый вариант - разработать инструмент, заточенный под конкретные потребности​

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

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

• Потребность в команде аналитиков, разработчиков и тестировщиков.
• Затраты на разработку, внедрение и развитие (как временные, так и финансовые).

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

Спасибо за внимание! Если у вас есть вопросы или нужна дополнительная информация, пожалуйста, не стесняйтесь обращаться!

Рад приветствовать вас на этой странице.

Хотел поделиться с вами историей создания данного проекта.

Много лет назад я работал аналитиком в одной крупной софтверной компании и мне приходилось разрабатывать техническую документацию к различным информационным системам. Это были технические задания, эскизные проекты, различного рода проектная и эксплуатационная документация. Заказчиками были крупные компании квазигосударственного сектора, поэтому разработка документации была очень важной частью проекта - она согласовывалась, утверждалась, в соответствии с ней велась разработка информационных систем. При необходимости что-либо дорабатывать в системах, соответствующие изменения вносились и в документацию. Необходимость постоянно вносить изменения в документацию приводила к накоплению в ней неточностей в виде неправильных ссылок, некорректно пронумерованных шагов в описании процессов, разночтений в разных диаграммах и их рассогласование с текстовым описанием. Все это снижало качество документации и мне постоянно хотелось автоматизировать какие-то вещи в этой рутинной работе. Поскольку и сейчас многие сталкиваются с похожими проблемами с документацией, а многие сталкиваются с её частичным и даже полным отсутствием, мне с коллегами пришла в голову идея автоматизировать процесс ведения документации и воплотить в новом инструменте нечто большее - функционал, который позволит бы ИТ архитекторам и системным аналитикам значительно упростить свою работу, и даже вывести её на качественно новый уровень, но обо всем по порядку...

Значительная часть документации, которую мне доводилось встречать и которая выделялась своей полнотой, детализацией, а также простотой восприятия, представляла собой описания на языке UML (Unified Modeling Language). UML это унифицированный язык моделирования, используемый для визуализации, спецификации, проектирования и документирования информационных систем. И именно поэтому, при реализации этой системы мы решили сосредоточиться на артефактах в виде UML диаграмм и спецификаций UseCase-ов.

В языке моделирования UML диаграммы UseCase-ов являются ключевым верхнеуровневым инструментом для моделирования требований. Они помогают визуально описать взаимодействие пользователей с системой и становятся основой для детальной проработки архитектуры, поведения и структуры программного продукта. Use Case диаграммы показывают какие категории пользователей взаимодействуют с системой и какие основные функции им доступны. Диаграмма не показывает деталей работы каждого сценария, и здесь на помощь приходят спецификации UseCase-ов - развернутое текстовое описание каждого сценария.

Спецификация UseCase-а - это структурированное описание одного конкретного сценария работы системы. Она отвечает на вопросы: кто инициирует процесс, какие шаги выполняются, какие есть альтернативы и что будет в случае ошибки.

Пример структуры спецификации Use Case-а​

• Название Use Case-а – что именно делает пользователь.
• Описание – зачем этот Use Case нужен, какого результата он позволяет достичь.
• Актёры – кто участвует в сценарии.
• Прототип интерфейса пользователя - экранные формы.
• Предусловия – что должно быть выполнено до начала сценария.
• Постусловия – варианты финального состояние системы после выполнения Use Case-а.
• Основная последовательность (поток событий) – пошаговое описание нормального выполнения.
• Альтернативные последовательности – возможные вариации сценария.
• Исключительные ситуации – ошибки, сбои, нештатные ситуации.
• Спецификации к шагам сценария - описание структур данных, коды сообщений об ошибках и прочая информация.

Используя такой структурированный подход к описанию функциональных требований можно добиться:

• подробного и детального описания особенности работы планируемого к реализации функционала;
• возможности предметного обсуждения требований с заказчиком и заинтересованными лицами, минимизируя риски рассинхронизации ожиданий и результатов реализации;
• точной оценки трудозатрат на реализацию требований, эффективного планирования работ и отслеживания прогресса;
• переиспользования документации в качестве готовых сценариев тестирования, которые могут служить как готовые требования на автоматизацию тестирования, так и для проведения ручного тестирования, в том числе в процессе проведения приёмо-сдаточных испытаний.

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

Тем не менее, без использования специализированных программных средств работа с такой документацией может приносить определенные неудобства - например, отсутствие инструментов рефакторинга такой документации, отслеживания изменений свойств одного и того же объекта в разных частях объемной документации, да и банальное ручное изменение нумерации шагов в последовательностях при их изменении может приводить к утрате целостности и непротиворечивости в описанных сценариях.

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

Подробнее о возможностях системы и перспективах её развития читайте здесь, а если желаете почитать о сравнении разных подходов, которые часто используют компании для документирования ИТ-архитектуры, то вам сюда :-)