Designing architecture
Designing solution architecture is about making best possible choices in context of current requirements and constraints. Behind every architecture decision there is some context and every architect should document the reasons of important decisions that are made. This article will focus on how to document architectural decisions in the context of project requirements in Sparx Enterprise Architect.
Value of architecture documentation
As an architect one needs to document important issues, possible solutions and reasons for choosing one of the solutions. There are various reasons to document decisions in projects lifecycle:
-
Reasoning that stood behind a choice will blur with time so the architect will not be able to precisely discuss or defend the choices or evaluate if the decisions made are still valid
-
Architect may need to describe reasons for his decisions for various reasons like some other architect joining the team or client (or consultancy company hired by client) having some questions about the design
-
Requirements and constraints may change in time and decisions may have to be reviewed. Knowledge about full context behind decisions made is fundamental in review them.
-
Architect may choose to leave project or for some other reason other architect may have to take over the responsibilities of the architect who originally made the decisions
-
Building database of architectural patterns and decision will allow the company to learn with every project, instead of relying on memory of individuals
Software architecture is also the dominant factor contributing to poor software architecture quality metrics of system. Bad architecture choices lead to costly development and maintenance and poor extensibility. They also have a tremendous impact on other software architecture quality metrics of system as reliability, scalability or testability. SEI has done research in this area, see A Field Study of Technical Debt [1]. Documenting architectural decisions is one of TOGAF's principles [2].
What to document
Deciding on what to document requires experience. Documentation must be lean and contain enough information to be helpful. A very good analysis is available in Sustainable Architectural Design Decisions [3] article, you can also find many blog posts or discussions on this subject on forums and social media portals. One thing to remember is that software architecture documentation is not a replacement for low level design documentation (if such is provided in project) or documenting code. You can also read about what to document in Documenting Software Architectures: Views and Beyond [4].
Deciding on what the documentation should contain also depends on the project. As discussed in Sustainable Architectural Design Decisions [3] formal documentation with many fields will in many cases result in gradual degradation of quality of documentation and even questioning the business value of documenting software architecture at all. A minimalistic and lean documentation may contain:
-
Issue name – a short name to identify issue in human readable form
-
Issue statement – description of the issue in textual form
-
Context (this includes requirements) of the issue – context should include functional requirements, non-functional requirements and other factors that have impact on decision.
-
Descriptions of alternative solutions - description in textual form
-
Reasons for choosing one solution - description in textual form
-
Status of decision – one of a few states
-
Date of last modification or evaluation
Depending on specific context or requirements other information may be included of course.
Where to keep documentation
Decisions can be kept in various places like:
Using case tool that is used to model requirements ha an advantage of keeping all data together and allowing to do searches on data easily. One of the important aspects of documenting software architecture decisions discussed in Sustainable Architectural Design Decisions [3] is keeping decisions with requirements.
Sparx Systems Enterprise Architect is an example of a CASE tool that allows architects to document the software architecture design decisions with links to the requirements. Sparx Systems Enterprise Architect is often used to manage requirements, design the solutions architecture and to convey design to development teams. Using Sparx Enterprise Architect makes it possible to keep requirements, architectural issues log and other design artifact (like state machines, process models, service models) in one place and to create connections between issues and requirements. This allows us to partially or fully automate process of selecting issues that need to be reviewed. Additional benefit of using Sparx Enterprise Architect is the document generation features of Enterprise Architect. It is possible to keep all requirements management, analysis and design data in Enterprise Architect and to generate documentation straight from EA. Other artifact like notes made on meetings that have impact on design may also be included as linked documents or as a simple link to version control system.
Using Sparx Enterprise Architect and UML Profile
To efficiently store architectural decisions in Enterprise Architect one should create a profile. It is possible to create an architectural decisions log without a profile, using one of extension mechanisms of UML like stereotypes or tagged values. Using profile gives us a better separation between model elements and allows to search for some data in the model more easily. Custom document templates for linked documents can also be used to store architectural decisions - details on how to do this can be found in Enterprise Architect documentation [9]. Searching these documents would be more difficult as it would require to build custom application or a plugin. Using UML profile gives use more searching options.
Creating UML profiles is described well in Enterprise Architect documentation [5] so there is no need to repeat this information. This article will focus only on main steps of creating UML profile in EA.
In order to create a custom UML profile in Enterprise Architect you create a Profile element in the model (see [5] for details). Then you add required meta classes and stereotypes to the Profile element.
Architecture decision log profile should contain five stereotypes:
-
Architectural issues log – this stereotype extends package
-
Architectural issue – this stereotype extends package
-
Architectural context – this stereotype extends artifact
-
Architectural decision - this stereotype extends artifact
-
Architectural alternative solution - this stereotype extends artifact
Architectural issues log and Architectural issue stereotypes extend package in order to be containers for other elements. Architectural issues log will contain many Architectural issues.
Each issues will have it's own packages in order to lessen the maintenance cost for Enterprise Architect model in the context of document generation. If we would keep them in one package then ordering the elements would be problematic, especially if later some new alternative decisions would be added.
Architectural issue will store description of the problem and a short title (we wont to keep the log simple). Architectural issue will also group architectural issue context, decision and alternative solutions. Each context must be connected via a trace relation to the requirements that engendered this issue.
Architectural context element will specify known constraints (both technical and non-technical) that limit possible solution space.
Architectural decision will contain reasoning on why the solution was chosen. This should be a short text as every alternative solution should contain advantages and disadvantages of a given solution that will give a good insight on each solution. This model allows to work with alternative solutions more easily, each solution has its dedicated element so they do not get mixed up making them harder to read.
Each Architectural issue will contain a number of Architectural alternative solution. Each solution alternative is independent solution option.
Architectural issues log is a package that will group various architectural issues.
This profile will contain necessary fields to convey information discussed in previous chapter:
-
Issue name – the Architectural issue element name (Enterprise Architect provided it)
-
Issue statement – the description of Architectural issue element
-
Context (this includes requirements) of the issue – Architectural context element will specify known constraints (both technical and non-technical) in it's description.
-
Descriptions (free text) of alternative solutions – the description of separate Architectural alternative solution elements
-
Reasons for choosing one solution (free text) - the reasons will be described in Architectural decision element's description
-
Status of decision – the status field of Architectural decision element
-
Date of last modification or evaluation – this will be the date on Architectural decision element
All the elements are shown on the diagram below:
In order to be used the profile must be first exported from Enterprise Architect as a profile and then imported as a resource. To export the profile right click the profile's package element and select Advances and then Save Package as UML Profile (see image below):
To import the profile right click UML Profile In Resources view and then choos Import Profile:
After doing this a new category of tools will be available. Image below shows an example of a small decision log created using this profile:
Custom model search
When we have the profile in place we can create a custom search that will allow us to find the decision for which requirements have changed. Both elements have last modification date so it is easy to track down issues that need to be reviewed.
We can do it in several ways:
-
Building a custom application that will use Enterprise Architect automation interface [6] to search repository – this requires a custom application to be build prior to executing any searches. Application would not be integrated with Enterprise Architect.
-
Search the Enterprise Architect database – using database level searches may be problematic as there may be differences between Access and some RDMBS' SQL executed to search the model for issues to review. Additionally if this solution will be chosen then search would not be integrated with Enterprise Architect.
-
Create Enterprise Architect plug-in - similar but not the same to building custom application. Plugin would be integrated with Enterprise Architect and thus more convenient to use.
-
Do a custom model search using Enterprise Architect extension features – the only thing required is to build a query and let Enterprise Architect handle query execution.
Last solution is quite simple and thanks to the fact that it uses Enterprise Architect extension features user will work with Enterprise Architect only to manage Architecture Decisions Log.
Such custom model search can be created in two ways:
-
With query designer
-
With SQL queries
Second option is more powerful but a little bit more difficult. There is a very good description on how to create such query on Bellekens blog [7]. In our case we will search for objects with type “Architecture issue” and choose those for which the requirements changed. The query that does this search can be found below:
select decision.ea_guid as NodeGUID, decision.name as Name
from (((( t_object req -- start with requirements
-- go to dependency connector
inner join t_connector requc on requc.End_Object_ID = req.Object_ID)
-- get Architectural decision context
inner join t_object ctx on requc.Start_Object_ID = ctx.Object_ID)
-- go to dependency connector for decisions
inner join t_connector decon on decon.End_Object_ID = ctx.Object_ID)
-- get Architectural decision
inner join t_object decision on decon.Start_Object_ID = decision.Object_ID)
where ctx.Object_Type = 'Artifact' and ctx.Stereotype = 'Architectural context'
and decision.Object_Type = 'Artifact' and decision.Stereotype = 'Architectural decision'
and decision.ModifiedDate < req.ModifiedDate
Description of columns and tables used:
Using this simple query we can quickly validate our model and see what needs to be reviewed.
In order to extend the query by adding some columns not covered in this example than be sure to take a look at Read Inside Enterprise Architect [8] site.
Conclusions
Keeping project documentation together is important for maintenance and architectural solution library. Creating such library must not be too much burden so it will not become an unwanted task. With Enterprise Architect and custom profile creating such portfolio is easy. Keeping all project information in one place makes it possible not only to maintain decisions by checking if they are valid or learn on past decisions and reuse them. It also allows to build cohesive and comprehensive project documentation. Thanks to Enterprise Architect powerful reporting features we can generate documentation for the projects straight out of Enterprise Architect. Architecture decisions are part of projects documentation, a very important part so they need to be included. No more copy & paste of diagrams and their descriptions.
Links
[1] http://blog.sei.cmu.edu/post.cfm/field-study-technical-debt-208
[2] http://pubs.opengroup.org/architecture/togaf9-doc/arch/chap23.html#tag_23_05
[3] http://www.infoq.com/articles/sustainable-architectural-design-decisions
[4] http://resources.sei.cmu.edu/library/asset-view.cfm?assetid=30386
[5] http://www.sparxsystems.com/enterprise_architect_user_guide/10/extending_uml_models/workingwithprofiles.html
[6] http://www.sparxsystems.com/enterprise_architect_user_guide/10/automation_and_scripting/automation_interface.html
[7] http://bellekens.com/2011/01/14/harvesting-the-power-of-eas-sql-searches/
[8] https://leanpub.com/InsideEA/read#search-builder
[9] http://www.sparxsystems.com/enterprise_architect_user_guide/10/modeling_basics/linked_document_templates.html
In order to use this search create a new search of type SQL and paste the above query into the query builder field.