Архитектурная документация. Часть 1. Documenting view

2019-09-11 14:51:12 +0600 +0600

Solution architecture Documenting a View

Мой перевод части статьи

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

Первая секция документации

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

Вторая секция - легенда, пояснение, словарь

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

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

Кроме того, если есть элементы или отношения, относящиеся к вью, которые были опущены в первичном представлении, каталог(легенда) представляет собой место, где они представлены и объяснены.

Третья секция - Контекстная диаграмма

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

Например, во вью «компонент и коннектор» показано, какой компонент и коннекторы взаимодействуют с внешними компонентами и соединителями, через какие интерфейсы и протоколы.

Четвертая секция - Variability guide (я так и не придумал как это на русском сказать)

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

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

Пятая секция - Бэкграунд

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

• Обоснование, объясняющее, почему были приняты решения, отраженные во вью, и почему альтернативы были отклонены.

• Результаты анализа, которые обосновывают дизайн или объясняют, что должно измениться в случае изменения.

• Предположения, отраженные в дизайне.

Шестая секция - глоссарий

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

Седьмая секция - Разное

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

Заключение

Мой перевод части статьи

Тут я описал только подход к виду документа. В оригинале еще есть что почитать.