Привет, Хабр! Меня зовут Мария Бурханова, я технический писатель, старший руководитель ИТ-направления документирования Platform V в СберТехе. На TechWriter Days я рассказывала, как техническому писателю научиться читать и понимать сложные нотации, чтобы сделать документацию простой и понятной.

Сегодня хочу рассказать, зачем техпису нужны нотации и почему их так много, какие знания о нотациях точно пригодятся и как применить эти знания на практике.

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

Почему нотаций так много и зачем они техпису

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

Давайте на примере блок-схем рассмотрим, почему понимание нотаций полезно для техписа.

Блок-схема — последовательность шагов процесса или алгоритма, изображённая с помощью различных геометрических фигур, соединенных стрелками. Основные элементы:

• стрелки — направление потока управления от одного блока к другому;

• ромб — точка, где необходимо принять решение на основе условия;

• прямоугольник — действие или операция, выполняемая в процессе;

• параллелограмм — ввод/вывод данных;

• круг/овал — начало и конец.

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

Инструкция по приручению лисы

1. Знакомство с лисой. Начните с наблюдения за лисой, чтобы понять её поведение и привычки.

2. Изучение привычек лисы. Изучите, как лиса питается, играет и отдыхает. Это поможет вам лучше понять её потребности.

3. Подготовка к приручению. Решите, готовы ли вы начать приручение сегодня. Если нет, продолжайте наблюдение.

4. Приручение. Если вы готовы, начните постепенно приближаться к лисе, делая это медленно и осторожно. Предложите лисе лакомства и игрушки, чтобы привлечь её внимание:

   1. Если лиса проявляет интерес к лакомствам и игрушкам, она делает «фыр-фыр». Это хороший знак, продолжайте общение и уход за ней.

   2. Если лиса не проявляет интереса, она может сделать «кусь». В этом случае лучше отступить и попробовать позже.

Следуя этим шагам, вы сможете постепенно приручить лису и установить с ней дружеские отношения.

При создании блок-схем или любых схем, показывающих шаги процесса, можно использовать разные подходы:

• интуитивный — просто рисуйте блоки и стрелки, как вам кажется логичным для процесса;

• UML-диаграммы активности — хоть они и предназначены для объектно-ориентированного анализа и проектирования ПО, но хорошо подходят и для визуализации шагов, решений и состояний;

• ГОСТ 19.701-90 — стандарт, где описаны правила построения схем для алгоритмов, программ и данных.

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

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

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

• Объектно-ориентированный: используется концепция объектов, которые отражают реальный мир. Универсальным инструментом для моделирования таких систем стал UML (Unified Modeling Language, унифицированный язык моделирования). Это графический язык, который описывает процессы и структуры программного обеспечения с помощью диаграмм и схем.

Есть и модели, которые не привязаны к подходу. Например, для бизнес-процессов используют стандарт BPMN (Business Process Model and Notation) — унифицированный графический язык моделирования, позволяющий описывать, визуализировать и анализировать потоки работ и взаимодействия между участниками независимо от способа разработки продукта.

Модели также различаются в зависимости от этапа разработки и уровня детализации:

1. Анализ требований. На этом этапе создают концептуальные модели. Они показывают основные классы и связи между ними на общем, абстрактном уровне.

2. Проектирование и спецификация. Здесь переходят к логическим моделям, где подробно описывают свойства (атрибуты) и поведение (методы) объектов каждого класса.

3. Реализация. На этом этапе строят физические модели — объединяют классы и другие ресурсы в программные компоненты и распределяют их по устройствам.

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

Какие знания о нотациях точно пригодятся техническому писателю

1. UML и plantUML

UML — это не только про иллюстрации, но и про текст (что вполне логично, ведь UML — унифицированный язык моделирования). Инструмент, с помощью которого можно превратить текст в графическое представление, — PlantUML.

Помимо UML-диаграмм PlantUML поддерживает другие форматы, связанные с разработкой программного обеспечения (такие как Archimate, блок-схема, BPMN, C4, схема компьютерной сети, ERD, диаграмма Ганта, Mindmap), а также визуализацию файлов JSON и YAML.

2. Варианты использования UML (use cases, диаграммы прецедентов)

Диаграммы прецедентов в UML описывают функции ПО без подробностей внутренней архитектуры. К ним относятся:

• действующие лица (акторы) — внешние сущности, взаимодействующие с системой (например, администратор, сотрудник, клиент);

• прецеденты (варианты) — действия системы, выполняемые для достижения цели актора.

Для удобства акторы и прецеденты можно группировать в пакеты, но это необязательно.

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

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

1. Варианты использования — это не все действия системы, а именно те, которые решают конкретную задачу актора. Варианты использования условно делят на категории:

   1. основные — ключевые сценарии задач (например, оформление заказа);

   2. вспомогательные — упрощают работу (например, архивирование данных);

   3. дополнительные — повышают удобство (например, автозаполнение формы).

2. Варианты использования связаны не только с акторами, но и между собой типами связи:

   1. ассоциация — сплошная линия, показывает взаимодействие актора с вариантом;

   2. расширение — пунктирная линия с меткой «extend», добавляет действия к основному сценарию (основной сценарий самодостаточен);

   3. включение — пунктирная линия с меткой «include», один сценарий включает в себя другой как часть;

   4. обобщение (наследование) — сплошная линия со стрелкой (пустой треугольник), показывает, что один сценарий наследует свойства другого.

3. Диаграмма последовательностей (sequence diagram)

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

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

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

4. Диаграмма состояний

Диаграмма состояний UML показывает состояния объекта, переходы между ними и события, вызывающие эти изменения. Она помогает понять жизненный цикл объекта и упрощает работу с системами, основанными на состоянии: к примеру, автоматическими дверями или сетевыми протоколами (например, TCP, который переходит между состояниями «установлено соединение», «передача данных», «закрыто» в зависимости от событий).

UML — популярная нотация и методология моделирования системы. Но ту же самую диаграмму состояний можно создать и по другим правилам, например, с помощью графов (сети Петри).

Чтобы показать, что сети Петри — это несложно, в шутку опишем технического писателя через «Цветные сети Петри» (это расширение классических сетей Петри, которое добавляет поддержку типов данных — цветов). Это простой пример, который помогает понять суть нотации. 

5. Моделирование баз данных

Crows Foot («воронья лапка») — нотация, которую благодаря своей наглядности и простоте широко используют в ER-диаграммах (Entity-Relationship Diagrams) для проектирования реляционных баз данных. Она показывает, как таблицы связаны друг с другом: «один-к-одному» (например, человек и его паспорт), «один-ко-многим» (например, клиент и его заказы) или «многие-ко-многим» (например, студенты и курсы).

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

На рисунке ниже лиса живет в «одной и только одной» тайге; а тайга связана с «множеством» лис, поэтому «воронья лапка» только около лисы.

Как применить знания о нотациях на практике

Представим, что у нас есть система — «Лиса». К нам пришёл аналитик и попросил разработать инструкцию для внешних пользователей о том, как приручить лису, и предоставил несколько моделей системы.

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

  Концептуальный уровень представлен в примере выше. Логический уровень (подробное описание полей и методов) может выглядеть так:

  

  Набросаем черновик инструкции:

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

  • Соберите ягоды.

  • Найдите лису.

  • Старайтесь не двигаться. Несмотря на то, что лисы хитрые и ловкие, они боятся человека.

  Почему мы не можем написать, что рыжие лисы появляются только в тайге? В диаграмме классов есть два типа отношений «часть от целого» — агрегация (не закрашенный ромб) и композиция (закрашенный ромб). Если бы использовалась композиция, это означало бы, что лиса не может существовать без тайги: убрав класс тайги, исчез бы и класс лисы, поэтому мы бы написали так: «Рыжие лисы появляются только в тайге».

  Но у нас агрегация, поэтому в контексте этой диаграммы лиса ассоциируется с тайгой, но не зависит в плане существования (если не станет тайги, лиса переберётся в еловый, например, лес).

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

• Диаграмма состояний — это своего рода карта состояний, через которые проходит лиса, и событий, которые вызывают эти изменения. У нас есть две диаграммы. На состояние «Расстроенная лиса» влияет событие «Игра с лисой». Мы поймём, что лиса стала весёлой, когда она сделает кусь и начнёт издавать тоновый сигнал. Чтобы у лисы состояние трусливости перешло в состояние любви, нужно её покормить ягодами, после чего вокруг лисы появятся красные сердечки.

  

  Набросаем черновик инструкции:

  • Поиграйте с лисой. Когда она сделала вам кусь, вы её развеселили.

  • Покормите лису ягодами, чтобы перевести в режим любви (вокруг лисы начнут плавать красные сердечки).

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

  

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

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

  По аналогии посмотрим на вариант «Зарегистрироваться в системе». На диаграмме деятельности будут показаны не действия пользователя, которые он выполняет при регистрации, а действия системы: проверка введённой информации, создание учётной записи, отправка подтверждения на электронную почту и т. д.

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

  • Поиграйте с лисой. Подайте ей игрушку. Когда лиса сделала вам кусь, вы её развеселили.

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

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

  • Как только лиса подойдёт достаточно близко, покормите её ягодами.

Мы разобрались с базовыми принципами нотаций, идентифицировали диаграммы и схемы, набросали небольшие текстовые инструкции. Соединили все наброски и разработали общую инструкцию о том, как одомашнить дикого зверя. Как итог — сэкономили время своих коллег.

Выводы

Модели описывают систему с разных сторон при помощи нотаций — условных языков. Нотации бывают графические (модели в виде графов, диаграмм, таблиц, схем) и текстовые (описания моделей на искусственных и естественных языках).

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

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

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

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

В качестве подсказки я сделала схему, некую модель знаний. Я не пользовалась никакими нотациями и следовала лишь своей интуиции. Этой схемой я хочу поделиться здесь.

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

Ресурсы и инструменты для изучения нотаций

• Инструменты для работы с UML (редакторы):

  • https://www.planttext.com/

  • https://plantuml-editor.kkeisuke.com

• Книги и учебные пособия по UML:

  • «Моделирование на UML», Ф. Новиков, Д. Иванов

  • «Самоучитель UML», А. Леоненков

  • «Язык UML. Руководство пользователя», Г. Буч

  • «UML. Основы», М. Фаулер

• Справочные руководства:

  • Справочное руководство по языку PlantUML

  • Справочное руководство по UML с быстрым стартом

  • Справочное руководство «Неочевидный PlantUML»

• Статьи и образовательные материалы:

  • Статьи с заданиями про разные виды диаграмм

  • Цикл статей про UML — обзор основных типов диаграмм:

    • Часть 1: Диаграмма классов

    • Часть 2: Диаграмма компонентов

    • Часть 3: Диаграмма объектов

    • Обзор 14 диаграмм UML

    • Статья «UML для самых маленьких: диаграмма классов»