Why on earth did we decide that way back then? Who hasn't wondered during development what the basis for an architectural decision was? When developing complex systems, decisions have to be made again and again. Important architectural or design decisions should always be documented. But what's the best way to do this? This short guide is intended to help with documenting architectural decisions.
How do you proceed?
It's a good idea to use a fixed scheme. I've depicted this scheme as a flowchart in the figure below.
Question and problem description
Before you can make a decision, you first need to clearly define the question or problem description. Only a good question can be answered appropriately. Therefore, it's worthwhile to consider the question or problem description at the beginning. This also has a very positive side effect. Other project participants (customers, developers, project managers, system architects) can intervene if the wrong question is being answered. I've often experienced situations where the question wasn't clear. A misleading question can lead to an unfavorable decision.
impact
Those who make decisions must be willing to live with the consequences. For example, using a brighter display with a higher resolution can affect manufacturing costs and power consumption. A decision can only be made if the consequences are known and accepted.
Influencing conditions and boundary conditions
In reality, there are constraints and influencing factors that limit the number of possible solutions. These constraints must be taken into account when making decisions. For example, the volume of a device must not exceed one liter. This constraint must then be considered in the architectural decision.
Assumptions and risks
If only we always knew what consequences a decision could have. Unfortunately, that's not always possible. But what we can do is become aware of the risks and record the assumptions. Therefore, we should state which assumptions were used in the decision-making process and which risks were identified.
Consider and evaluate alternatives
Ideally, there are several alternative competing solutions. Using a decision matrix, the alternatives can be compared and evaluated according to established objective criteria. This leads to objective decisions that are understandable to everyone.
Document the decision and justification
Finally, you've reached your goal. The decision has been made. Then you should record this decision, and especially the reasons why you made it. You can use the decision matrix, for example, to help you with this.
|
|
| Dipl.-Ing. Goran Madzar, Partner, Senior Systems Engineer E-mail: madzar@medtech-ingenieur.de Phone: +49 9131 691 240 |
|
Do you need support with the development of your medical device? We're happy to help! MEDtech Ingenieur GmbH offers hardware development, software development, systems engineering, mechanical development, and consulting services from a single source. Contact us. |
|
What's the point?
In my experience, a structured approach leads to better architectural decisions. The approach described here is not just about documenting the decision, but also about applying a sound decision-making process. Only after having familiarized yourself with the steps described above can you make a sound decision. Other project participants can understand and support the decision or raise their concerns in a timely manner. The decision-making process is made transparent and remains understandable even years later.
In what format should this happen?
Decisions should never be documented in emails, in the lab notebook, or on the whiteboard. It is advisable to use concept documents for architectural decisions, with a chapter structure based on the approach suggested here. In such a document, you have the space necessary for decision-making. You can refer to the concept documents in the system architecture or in design documents. I would not document the decisions in full in the system architecture so as not to overload the document. In my opinion, the system architecture should only describe the implementation and not all the options investigated. If you use ALM tools (such as Polarion), they also offer the option of adding comments to specific work items (requirements, architectural elements). This functionality is very useful for documenting knowledge without changing formal documents.
I'm very happy to receive feedback and engage with you. Feel free to comment on this article. If you know someone who might also be interested in the blog, I'd be delighted if you would share it with them.
Best regards
Goran Madzar