Documentat.io

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

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

• Как правильно поставить задачу? Идентификация предмета описания: как определить, что именно является архитектурой в конкретном случае. Учимся не путать архитектурные уровни: от корпоративной архитектуры до архитектур компонентов. Выявление адресатов архитектурной документации и их информационных потребностей. Определение целей, задач и критериев качества архитектурной документации. Составление корректных требований к архитектурной документации, их защита и утверждение у заинтересованных лиц.

• Как подготовиться к документированию архитектуры? Состав умений и знаний, необходимых любому разработчику архитектурной документации. Основные архитектурные подходы, паттерны и компромиссы. Монолитные, микросервисные и агентские архитектуры. Понятие паттерна и важнейшие паттерны (фабрика и синглтон — мимо). Особенности архитектуры высоконагруженных систем, CAP-теорема. Топ-10 аббревиатур, не зная которых лучше не подходить к архитектору.

• Как собрать, систематизировать и проверить информацию? Выявление источников и обладателей архитектурной информации. Техника архитектурного интервью. Архитектура “as is” или “to be”: не дайте себя запутать! Проверка полноты и достоверности собранной информации, заполнение информационных лакун. Эффективные приемы ведения рабочих протоколов и таблиц.

• Как описывать архитектурные решения?

  • Основные стандарты и фреймворки, влияющие на архитектурные описания: ISO 42010, TOGAF ADM и др. Основные виды архитектурных документов: Architecture Vision, Architecture Definition Document и др. Адаптация международных подходов к отечественной терминологии, отражение архитектуры в документации по ГОСТ.

  • Формирование терминологического и понятийного аппарата архитектурной документации. Приемы понятного описания архитектурных решений: структур, принципов действия, потоков данных, информационных моделей.

  • «Говори на языке диаграмм». Наиболее важные графические нотации для разных архитектурных уровней: ArchiMate, BPMN, C4, UML. Составление понятных схем и графических иллюстраций вне стандартных графических языков.

• Какие инструменты выбрать? Формирование технологического стека для ведения архитектурной документации. Почему Конфлюенс не решит всех проблем, а от Ворда все равно не уйти? Средства ведения репозиториев и конфигурационных баз данных. Выбор формата хранения и редактора текста документации. Редакторы и генераторы схем. Способы публикации архитектурных документов и их доведения до целевой аудитории. Связка CMDB → Docs as Code → Wiki. А может, за нас все напишет ИИ?

• Как сделать архитектурную документацию полезной? От «посмертной документации» к инструменту: делаем архитектурные документы неотъемлемой частью процессов жизненного цикла ИТ-решения. Структурное и семантическое ядро: делаем архитектурную документацию основой для документации в других контурах. От архитектуры “as is” к “to be”: легализуем разрыв между ними в виде роадмепа. Интеграция архитектурной документации с кодом и другими артефактами разработки.

• Как управлять разработкой архитектурной документации? Заключение «контракта» и разделение ответственности с другими участниками разработки архитектурной документации. Оценка трудозатрат на разработку, календарное планирование, управление сроками. Рецензирование, согласование и сдача архитектурной документации. Организационный Docs as Code: разработка документации спринтами. Как не остаться виноватым: работа в условиях архитектурных кризисов и конфликтов.

Формат курса

Остались вопросы?