В настоящее время я пересматриваю несколько шаблонов документов для своей компании. Одна вещь, которой у нас никогда не было, - это формальная спецификация архитектуры, поэтому я начинаю складывать ее вместе.
Какие вещи вы вкладываете в свои спецификации архитектуры? Не стесняйтесь копировать и вставлять оглавление - это было бы полезно. Есть ли хорошие шаблоны, уже доступные в Интернете?
Я согласен с чувством Асафоса; к счастью, невозможно сделать полезную/практическую архитектурную документацию - просто не принято.
Для меня главное - понять, для кого предназначен документ: когда они будут его использовать? Зачем им это использовать? Слишком много раз это просто становится упражнением по заполнению формы для тикающих ящиков на каком-то плане проекта.
Я предполагаю, что вы имеете в виду документ архитектуры программного обеспечения или документ архитектуры решения, а не стратегию предприятия или что-то в этом роде.
Помните также, что есть две вещи, которые типичный документ архитектуры будет делать:
С точки зрения как структуры, так и ключевой информации для захвата я бы рекомендовал взглянуть на различные представления системы: логические, физические, данные, безопасность и т.д. Хорошей отправной точкой является 4 + 1 модель.
[Обновить:] Одним из видов использования артефакта является Traceability - от требований и дизайна артефактов до артефактов кода; и, хотя это может показаться, что "Водопад" ориентирован, он фактически применяется (и работает) для проектов на основе Agile.
[Обновить:] Артефакт не означает "Word Document". Ниже приведен пример ToC - это поддерживающая версия на основе документа/документа, смоделированная в инструменте моделирования UML (SparxEA), которая также включает в себя требования. Иногда вы "должны" использовать документ, но я стараюсь быть максимально экономным.
[Обновление:] Другая хорошая вещь о хорошем четко изложенном документе заключается в том, что для новой крови легче понять, что они наследуют, особенно если предыдущий персонал недоступен.
Институт инженерии программного обеспечения в Carnegie Mellon имеет кучу информации, а на приведенной ниже странице есть ссылка на шаблон: http://www.sei.cmu.edu/architecture/tools/viewsandbeyond/
Заболел, что он очень всеобъемлющий - не для слабонервных (или не хватает времени).
[Обновить:] Наконец, здесь приведен пример содержания из недавнего проекта. Несмотря на то, что во многих разделах документ не слишком длинный (всего около 35 страниц, и большая часть этого - диаграммы).
Table of Contents
1 Documentation Roadmap
1.1 Document & Version Information
1.1.1 Document Contributors
1.1.2 Referenced Documents
1.1.3 Reviewers
1.1.4 Document Signoff
1.2 Glossary of Terms
1.3 Purpose and Scope of the SAD
1.4 Stakeholder Representation
2 Project Background
2.1 Problem Background
2.2 Solution Overview and Project Phases
2.3 Solution Context
2.3.1 Solution Usage
2.4 Architectural Goals
2.5 Constraints
2.6 Considerations
3 Register of Issues and Decisions
3.1 Issues Register
3.2 Decisions Register
4 Overview of Key Views
5 Functional View
6 Logical Layers View
7 Physical View
7.1 Mapping of Logical and Physical Components
7.2 Mapping of Logical Layers and Bespoke Packages
7.3 Bespoke Physical Components
7.4 Common
7.5 Business Logic
7.6 Data Provider Interfaces
7.7 MS SQL Data Provider
7.8 Data Repository
7.9 External Data Services – Time Sheeting
7.10 External Data Services - DLR
7.11 UI - Flash
7.12 FlourineFX
7.13 UI - ASP.NET
7.14 Model
7.15 Login
7.16 Mapping To Physical Components
7.17 Solution Dependencies
8 Solution Views
8.1 Data View 23
8.1.1 Conceptual Data Model
8.1.2 Physical Data Model
8.2 Technology View
8.2.1 Microsoft Windows Server
8.2.2 Microsoft Internet Information Server
8.2.3 Microsoft SQL Server
8.2.4 Microsoft .Net Framework
8.2.5 Microsoft ASP.NET
8.2.6 Microsoft ASP.NET Role Membership Provider
8.2.7 Dot Net Nuke (DNN)
8.2.8 AntiXSS Library
8.2.9 Microsoft Enterprise Libraries
8.2.9.1 Application Logging Block
8.2.10 Log4Net
8.2.11 Fluorine
8.2.12 Adobe Flash
8.3 Security View
8.3.1 Data Encryption – Data at Rest
8.3.2 Data Encryption – Data in Flight
8.3.3 Authentication
8.3.4 Authorisation
8.3.5 Non-Repudiation
8.3.6 Cross-Site Scripting (XSS) and SQL Injection
8.3.7 Other Security Concerns
8.4 Infrastructure View
8.5 Support View
8.6 Enterprise Standards Compliance
9 Design Patterns and Principles
9.1 Dependency Inversion Principle
9.2 Dependency Injection Pattern
9.3 Factory Pattern
9.4 Persistence Ignorance
9.5 Dependency Injection
Appendix – [legacy project name] Phase 1
9.6 Bespoke Physical Components
В моем личном мнении я считаю следующие темы полезными при определении Документации по программному обеспечению:
Взгляните на эти Руководство по архитектуре приложений от Microsoft:
Мои типичные ингредиенты для спецификации архитектуры:
Также посмотрите 4 + 1 Model.
IEEE имеет множество стандартов в соответствии с этой проблемой. Например, IEEE 1016, он определяет организационную структуру описания программного обеспечения. http://en.wikipedia.org/wiki/Software_Design_Description
Документ должен содержать как минимум следующие главы
Архитектура должна обеспечивать руководство разработчиками таким образом, чтобы избежать проблем интеграции и обслуживания. Более конкретно, архитектура должна идентифицировать такие вещи, как утвержденные операционные системы, утвержденные языки разработки, утвержденные системы хранения данных, утвержденные протоколы связи, методы кодирования, рамки тестирования, контроль источника, процедуры принятия пользователем и процедуры выпуска продукции, разделение проблем, процедуры обслуживания и безопасность. В большинстве случаев это живой документ, и разделы добавляются и уточняются по мере совершенствования технологий. Поскольку каждая компания уникальна, копия руководства будет полезна только для идей того, что включать. Основываясь на ответах других, у вас уже есть ряд замечательных идей, которые вы можете использовать.
"Спецификация архитектуры" будет очень ограниченным термином. "Архитектурная документация" будет правильным термином.
Цель архитектора состоит в том, чтобы иметь системный дизайн для удовлетворения не функциональных требований (NFR) атрибутов QoS (Quality of Service) (например, масштабируемость, доступность, производительность, надежность, безопасность, расширяемость, ремонтопригодность, управляемость и т.д.). который поддерживает основные бизнес-функции.
Вам нужно будет документировать атрибуты QoS, которые важны для вашей системы, и какие варианты дизайна вы сделали для их реализации. Эти атрибуты Qos взаимосвязаны, и вам, возможно, придется сделать некоторые сделки, поэтому вы должны упомянуть эти компромиссы с соответствующими аргументами.
Для достижения QoS вы будете систематически разлагать свою систему по распределению, уровням (уровеньу/слою), воздействию, функциональности, общности, сцеплению и сплоченности, волатильности, конфигурируемости и т.д. Это можно рассматривать как "Специфика архитектуры", за ними последуют разработчики для реализации различных компонентов в системе.
Как развертывается система, также влияет на QoS. Вам нужно будет документировать сетевую и аппаратную инфраструктуру и как приложения будут развернуты на этом оборудовании. Как увеличить емкость системы (вертикально/горизонтально) или увеличить избыточность.
Это обсуждение:
В RUP: Какие роли RUP отвечают за создание документа по архитектуре программного обеспечения?
предоставляет этот шаблон:
http://www.ts.mah.se/RUP/RationalUnifiedProcess/webtmpl/templates/a_and_d/rup_sad.htm
и этот обзор документа SAD в RUP:
http://www.ts.mah.se/RUP/RationalUnifiedProcess/process/artifact/ar_sadoc.htm
Характеристики архитектуры служат для обеспечения высокого уровня обзора системы. Это помогает разработчику получить общую картину системы и помогает визуализировать взаимодействие различных подсистем. Как правило, архитектура охватывает множество выпусков продуктов, поэтому она должна попытаться покрыть ремонтопригодность, гибкость для ожидаемых требований.
Я думаю, что важно обеспечить достаточное освещение следующих тем в спецификациях архитектуры
Хорошо читать: https://www.amazon.com/Documenting-Software-Architectures-Views-Beyond/dp/0321552687
Вы должны написать свою архитектурную документацию со своими заинтересованными сторонами (например, разработчиками, клиентами). Взгляды и содержание зависят от того, что необходимо для заинтересованных сторон. Поэтому содержимое вашей архитектуры может варьироваться от проекта к проекту.