Requirements Realization Views

One of the most essential but often overlooked views to have on architecture is requirements realization. This blog explores this subject and one way we can work with them.

I show one way of working with Requirements Realization Views – Its not the only way. Doing this can save huge amounts of time and money by avoiding a need to redo things.

If you have read ISO 42010 the International standard for architecture description, you will know that every architecture view is intended to frame the concerns of its stakeholders.

Architecture isn’t about drawing pictures. Whist defining a view of technology is important, it is more important is understanding the reason why. We learn this in math class as children. The answer to a math question gives you points, but you also get points for showing work.

The Requirements realization view is one way to show how a solution meets the needs of its stakeholders.

I show below some example views and one way of working that can be used with BiZZdesign’s Enterprise Studio. Its the tool I use most often, so I leverage some of its benefits in my workflow. All the things I show can be done with other tools, some tools make this easier than others.

An Example View

Figure 1 – Requirements Realization View

The example above is a basic requirements realization view. Its at a high level – its showing that a product is meeting several requirements. The level of detail we go to depends very much on the benefit it would provide. The view in figure 1 – may serve as a good introduction to anyone wishing to understand the design from the Web Hosting Product. For the purposes of a high level introduction to business stakeholders that might be enough, but how do we know what is above is true?

The next level of detail

Each of the requirements in figure 1 is obviously a collection of other requirements – I might define them in architect, or I might just reference another source. For example – business unit requirements may exist and be managed in a system like Confluence. This might be a more accessible place for stakeholders to manage them if we do not want to go though the trouble of teaching everyone ArchiMate.

The next level of detail in ArchiMate

Personally, I do not always ask for everyone to go to the next level of detail in ArchiMate, because in a complex project with many moving parts it doesn’t always make sense, especially when you have different architects at different levels of maturity, especially when you have several thousands of requirements in a project

That said, there are advantages to mapping your requirements in Archimate. I know one or two architects that do it.

Using Enterprise Studio

Here tools can set you apart. Importing requirements from excel into an architecture model can be fairly easy in some tools. I am using BiZZdesigns Enterprise Studio (BES). – which makes it easy to import and update requirements if I create them using New > Multiple – I can then copy and paste in from excel. I could have done this other ways too and its probably worth the time taken to do that.. You end up with a lot of requirements on a view like this:

Figure 2 – Requirements

You might think in this case that this isn’t very helpful – its just a bunch of numbers – but what i did was import the requirement ID’s as names and I put the actual descriptions in the description or documentation field. In this way when I have many requirements I can make them smaller and more manageable on screen.

To actually see detail of each requirement I can switch on tooltips – so the documentation pops up when I mouse-over the requirement, or I can use labels.

Figure 3 – A requirement labelled.

So why bother?

Once I have the requirements on my canvas i can group them together – to organised them in different ways for different stakeholders. Something like in figure 4:

Figure 4 – Grouping Requirements

When I have done the above in big projects I have sometimes identified requirements that are not managed at all. In the example above you can easily see uncategorized requirements. They are not connected to anything and can easily be forgotten. Just by itself it makes the pain of the exercise worth while. I can also at this point prioritize them and then I normally take these requirements and connect them into a series of implementation and migration views.

Every requirement needs to be realized some how. I can pretty easily either script, or create a property table in Enterprise Studio to see requirements that are not realizing things as an extra level of validation. If we have mapped our requirements into groups, and created views for each group, then we should easily be able to see things that are not realized anyway. Back in figure 4 we did our mapping, and as a result of the mapping for example we may have decided to have 5 realization views:

  • Customer Requirements Realization View
  • Architecture NFR Realization View
  • Security NFR Realization View
  • Business Unit Requirements Realization View
  • Orphaned Requirements Realization View

Mapping Requirements to the Realization

Now with the prep work completed we get to the important part. Our Customer Requirements Realization View might look like something in figure 5.

Figure 5 – Customer Requirements Realization

Lets look closer at figure 5.

The standard web hosting solution

I make use of the grouping element in ArchiMate to represent architecture building blocks. Its enables me to keep things neat – I could have course have hidden this level of detail in another view & just connected in the Web Hosting Product. In this case I felt the services create value. I do not need the detail to know exactly which servers are being used but I can tell that this will be an Azure hosted solution, running on Linux. If you read my blog on services, you should at this point start to see the value of hiding architecture behind the externally facing services.

Standard Services Contract

Some requirements are covered by our standard products and some by our standard agreements. To use the ISO 42010 language again – Its important to see that concerns are all framed within one or more viewpoints. This means even if its obvious to us that something is covered in the standard contract we should state it. What is obvious to me is not necessarily obvious to a coworker.

Customer CRM

Of course I could put as much or as little detail as I need into this view. I am telling a story, which I talk about in my Improving Archimate Modelling Blog. The important thing to remember is that all requirements need to be realized in a view, but again not always the same view. Because we are telling a story we need to be consistent with the level of detail.

Locking Down Requirements

Before starting requirements realization its important to have requirements management under control. Its a separate subject, but you need to ensure that requirements are not significantly changing during a project, or the workload significantly increases.Going through the process of redrafting your realization view will provide benefit and avoid confusion.

Some Common Challenges

I have sometimes seen requirements realization being missed as a step. Sometimes people just create a technical solution, and say “yes” that meets the requirements after a first read through, Then later they realize it doesn’t because they didn’t look to this level of detail and are forced to go through a very expensive exercise of fixing things.

I have also seen things mess up because requirements management is seen as being a project managers job. Yes, those guys are responsible to ensure requirements are met, but not how they are met. I see the job of organizing requirements in a way that makes sense to the solution as being an essential part of an architects job. If you look at the TOGAF ADM for example you will see requirements management at the heart of everything..Its partly a separate conversation but I would also encourage architects to work with project managers to organize requirements in a way that makes sense, because it makes requirements realization a lot easier and reduces risk,

Another common issue if focusing too much on customer requirements. Its really common for organizations to have a customer first approach – but this doesn’t mean we should not consider our own needs. Business requirements are important, as are the architecture and security ones for example. If we do not consider them, issues will occur later – because they are there to mitigate risk. Some non functional requirements will relate to documentation and I can easily create a view for architecture deliverable requirements realization. In projects architects should ensure time is given to manage non customer requirements.

Summing It Up

I cannot stress the importance of doing requirements realization. In this article i focused mostly on doing requirements realization in ArchiMate, but we can actually do it in other ways. I wrote about the challenges of Designing Architecture Through Document Templates before – I personally try to avoid that for the reasons I state in that blog.

Requirements show us “what” needs to be done by “who”, and “when”. Requirements Realization shows us “how”. This is a message I think all architects should take to heart and communicate out to other stakeholders.

Yes, running through thousands of requirements can be boring but taking the time to properly manage and realize them can result in very high quality work. Requirements Realization can be cool.

Architecture Concerns

Architecture concerns are often misunderstood, partly because of the use of the word “concern”. This blog aims to provide some clarity around concerns and their use.

What is an architecture concern?

A stakeholder is a person who gets some kind of value from an architecture. A concern is something that a stakeholder wants.  This can be a request/requirement – such as a customer wanting an email service, or a service requiring  a database server, or it can be something more risk based – like customer being concerned with security. We tend to focus on the negative connotations of the word concern; in the Cambridge Dictionary Definition it has two meanings:

  1. To cause worry to someone
  2. To be important to someone or involve someone directly.

Definition 2. is the one that applies to architecture – the reason we talk about concerns is because that is the language used in ISO42010.

Putting it simple:

  • A requirement is a type of concern
  • A feature request is a type of concern
  • A worry is a type of concern
  • A risk is a type of managed concern.

What do you mean by a “risk is a type of managed concern”?

Concerns are addressed within architecture design. A risk happens when we formally accept a concern  that potentially has a negative impact on our goals and requirements.  

An example – Customer may have a requirement (one type of concern) which says they need administrative access to a server. 

If I have a goal to keep the servers secure and ensure their up time – as the architect I may have a concern that granting customer access to the server means that they can break something. My design needs to address the customer requirements and in this case we may have looked at the requirement and determined something that might be a risk. The concern should be taken to the stakeholders in the project (be it project managers/steering committee) and if it is formally accepted as a risk it is formally registered. However we still need to manage the concern.

What part does an Architect play in concerns management?

The architect role is key in concerns management. One of the reasons I speak so much about ISO 42010 is not only that its an internationally excepted way of describing architecture but it makes the relationship between concerns and architecture very clear – all concerns need to be framed within a view of architecture.

This may seem obvious but is sometimes missed – there are concerns – such as customer requirements and non functional security requirements (to name a few types). I’ve seen many cases where architects talk to different stakeholders, read the concerns then just build a technology based solution. The output a technical diagram; at that point they consider the work done.  When you take this approach without documenting how the technical diagram aligns with the concerns you are left with a few questions:

  • How do I know the technical solution meets all the customer and non functional requirements? / How do I know that all the concerns have been managed? Because if its not written down its easy to miss a requirement. Its possible to someone else is managing a concern also.
  • How do I know that we have correctly identified raised and managed all the correct risks from our concerns? Unless we look at each concern one by one ..

In the example above our concern over customer access turned into a risk but regardless of if it is a risk the process for the architect should still be the same because all concerns should be framed in a architecture view.

If a concern is easily met we can just state that – for example if a requirement if for high availability and we can say that “high availability is provided as part of standard design in our SharePoint Product” – that’s perfect. Having this stated it in your architecture design (or in an ArchiMate view) leaves no doubt that we have addressed things.

If we go back to our earlier example of admin access you could see there we had a problem – a conflict of interest that had to be resolved.  Normally that happens in one of several ways

  • Someone Accepts The Concern – A stakeholder should accept the concern – and who accepted it when should be documented in the design.
  • Someone Rejects the Concern – In which case this should also be documented in the same way
  • Something happens to mitigate the concern – This could be a change in the design – in which case you can document what the change is, and again why the change is needed and by whom/what.
Money!

Cost vs Benefit

Its important for an architect to manage and document the management of every concern one by one. Whilst this may seem laborious the reasons are simple – cost and risk. Consider this:

If an architect in a team of 5 project architects is working with 1 concern, its possible he may  be able to instantly say – yes its met by standard design or if its more complex he/she may spend a day validating the said requirement; to do that he may need to read or for example talk to 4 different people. in this case the time consumed may be:

  • 4 hrs reading
  • 4 hrs architect time in meetings
  • 4 hrs of another resources time
  • 1 hr documenting the work.

That’s 13 hrs of work on a single concern. If we manage it that way – then other resources that need to ensure the concerns are met can just look – lets say in our example a project manager is interested, a security manager, and another architect.  This would be another 3 hours if they read the documentation or 6 if they decided to talk to the architect directly – which they could do because they would know the architect managing the concern through looking at the design – in worse case though following the method it would be 19hrs of consumed time for the project to look at the concern.

Lets look at it from an unmanaged perspective. Project would not know who is looking after a concern and would actively have to check in over time. This means that just to check the status the project manager spends 6 hrs of time in a meeting (PM + Architect). If the security manager and another architect also needs to know whats happening we can end up spending  another 18 hrs of meeting time before even doing any work – then the meetings begin – a concern may be managed in one meeting – put into the meeting minutes then several months later on the same project the same question may come up… which is more meeting time. 

A single concern could end up costing hundreds of hours in project time.  multiply that out, and you will see that you end up with huge costs for very little result. Its a very inefficient way of doing things – where you should just have everyone referring back to a single design which clearly connects concerns to the solution.

Prioritizing concerns in a large project

There has to be a methodology behind prioritizing requirements/concerns in projects involving multiple teams. To do this, business takes priority over technology.  When multiple teams are involved a single architect has to coordinate the concerns – its not the job of a project manager to do this – project managers have to ensure the goals of the project are met, and to keep track of status but concerns have to be organised in a way that makes sense to architects, and managed in a fashion that plugs into architecture (reasons are given earlier). If project allocates out concerns then the chain of prioritization can be broken.

For example, on a large project we may have End User Services (EUS) being provided to a customer. the solutions architect pushes the customer concerns for EUS towards the end user services team. the end user services team will then look through those concerns, and some of them will be managed by themselves, and some will need to be allocated to teams behind them – for example, towards the platforms teams.  Its possible that end user services will have some of their own concerns that also need to be allocated towards their dependent teams. 

The concerns that EUS push towards the platforms team should be managed by the platforms team. If the platforms team cannot meet the concerns they should not just say “no”; they should be providing a solution & alternative. If we take this approach then all concerns are clearly managed and clearly owned, and driven from the direction of business towards technology – its important do do it in this direction because we need our architectures to be customer focused.

Having the basic discipline to manage concerns as mentioned above can save thousands of hours on a large project and can lead to much better control of risk and less cost and time overrun.

How do I express concerns?

I generally consider concerns to be a kind of requirement. Requirements can be captured in a number of different ways. I talk about them in various requirements related blogs – and have more blogs planned on this subject. When developing from scratch I often start with User Stories.

Summing it up…

Concerns management requires discipline and competent architects. Architects should have ownership of the management of concerns. The project managers still have a critical role to play in ensuring alignment to goals and schedules, the management of project status which includes having an overview of how concerns have been managed. The project manager doesn’t lead the management of concerns, but they do ensure that the correct parties are managing concerns and delivering results; if we think of this like a jigsaw puzzle, the project managers provide the pieces to the architects and make sure those pieces do not go missing, and may be letting everyone know just how much of our puzzle is complete, but the architect is putting the puzzle together.

Managing architecture concerns saves unnecessary meeting time, ensures that architects deliver good solutions rather than just good technology implementations. Quality goes up, and the changes of missing something, or having chaos in projects through misalignment or misunderstanding, and other cost overheads goes down.

To put it simply. If you are not managing your concerns you have a real risk that whatever solution is being provided to its stakeholders may not be fit for purpose.

Assessing Solution Requirements

In this blog I talk about requirements, and the process of choosing anything as an architect. It could be a hardware solution, like a suitable laptop, or a software decision like choosing between Teams and Slack. 

A really important thing to note here, its that its much more important to think about the methodology behind what I present here than the tools I use.

Choosing The Right Solution

As a rule of thumb, it’s always a good idea to assess 2-3 different technologies before choosing one. Its good to know if your primary option fails for whatever reason, there’s a secondary solution. We want to avoid vendor lock-in ; if there is only a single vendor we should risk assess them – which is a whole other subject unto itself.

Decisions should be made based upon the requirements of our different stakeholders to ensure that the solution is fit for purpose. Its tempting to look at software and think about the feature set that the software gives. Some people choose one piece of software over another because it has better features. This is normally a bad approach; you may end up paying for a solution that’s expensive that will never be fully utilized. The same approach equally applies to hardware and software.

When considering replacement technologies or upgrades you should also revert back to the requirements.

An Example With Disk Capacity

For example – If we are looking to order new disk capacity – a vendor may offer us a new model of disk capacity which is 5% faster. It may look at a good idea on the surface, but that’s not necessarily the case. If we do not require faster disk capacity, then in fact there may be a cost overhead. Let’s consider TELOS for a moment (Technology, Economy, Legal, Operational, Scheduling). We may realize that to implement new hardware means potential incompatibility and a risk to operational efficiency. It may also mean we need people to support or train with the new technology; its one more technology type to manage. 

In addition to this – we should of course be tracking decisions, in a work log or other system. We might also consider having release management on versions of our requirements and the approvals of them.

Modelling Device & Requirement Mapping

A practical example. I needed to choose a new laptop. Not knowing what to get I did an exercise in ArchiMate. I started by modelling the top choices I had narrowed down to (I created a Technology View). Of course, if we were deciding software items we could just as easily use application components in another view.

Laptop Device Elements

From there I needed to decide my requirements. I am using BiZZdesign’s Enterprise Architect and multi-added some items (it took 2 minutes). I followed this by using a property table to assign priorities to my requirements. The resultant requirements ended up looking like shown below. It’s a Motivation View, using a MoSCoW color filter:

Requirements View

You can see above the priorities in had on my requirements. Normally in doing requirements I am thinking about TELOS; we could also consider ensuring we capture requirements from all the different stakeholder types named in ISO 42010. Note, in my laptop decision I was doing quick and dirty modelling.

Realizing The Requirements

Once I had the requirements it was a matter of deciding which devices met the requirements. I could have put both the devices & requirements in a requirements realization view; Instead I used another cool Enterprise Studio feature – I created a cross reference table using these options:

Cross reference table definition

From here it created a table and I could just click on the table cells to generate realization relationships between the requirements and the devices.

Cross Reference Table

Visualizing this – it was easy to see the best option there was the EliteBook. I could have easily from this point generated a ArchiMate view if I wanted to using the auto-generate functions in enterprise studio but I just didn’t need it. I could have also saved this table as a Enterprise Studio Viewpoint and reused it later so I didn’t have to re-select the options again. Note – Viewpoints in this case refers the the Enterprise Studio functionality. In my agony to make the right choice I did in fact produce one last motivation view:

Motivation View

The whole exercise took 30 minutes.  There are distinct advantages to modelling your requirements; when it comes to making sure nothing is missed in requirements realization and tying requirements into other bits of architecture. We can of course document the requirement, its rationale, and influence.

Working With Larger Projects

When working as part of a larger project you might have to periodically sync requirements, or compromise on how you work with them – I could for example in a requirements realization view show a single element such as “Citrix Hardware Requirements”  and then in the documentation of the element just link to a confluence page where a team of people not using my modelling tool can manage them. 

We can also document the relationships; in relationship documentation you could express who had actually agreed or confirmed the requirement can be realized alongside any justification or documentation you have.

Capturing Requirements In A Collaborative Tool

We can capture requirements using any collaboration tool – be it something like OneNote or Confluence. Of course its good if the tool you use allows versioning; regardless of the actual tool you need to consider the following:

  • State who the requirements are for.
  • We clearly identify who is┬áresponsible , which product it pertains to, and other people that have been involved in identifying these requirements in a header block.
  • Sometimes I break requirements down following TELOS – to ensure whoever fills in the template considers things around Technology, Economy, Legal, Operational, Scheduling.

Minimum Needs For Requirements

Normally the actual requirements table as a minimum need has:

  • Who – is the source of the requirement
  • Service/area – gives an indication as to the general area/category of the requirement
  • The requirement – should be clearly defined and easy to validate (no fuzzy vague wording)
  • The rationale should explain why the requirement exists
  • Priority Follows MoSCoW (Must Have, Should Have, Could have, Won’t Have)
  • We have compliance columns for each option we assess.

The levels of compliance normally has the status, and the name of the person who has responsibility for meeting our requirement – for example, if we have a requirement for the network team someone in the network team needs to agree that they can fulfill requirements.The compliance statuses i normally include with the name:

  • Full – means that the device/service/software fully meets the requirement. 
  • Partial – Means the device partially meets the requirement. In this case we would also include words in this table cell to explain why it is only partially compliant.
  • Non Compliant – Is obvious – again the reason for non compliance should be stated
  • Undetermined – Means we have asked but just don’t have an answer yet.

Summing It Up…

Its important to capture requirements and then to assess different technologies against those requirements rather than to look at the feature set a tool or application gives us. If it looks like a solution has a feature we didn’t realize we wanted, this is a change in scope for our solution and we should reassess our business case.

In a world where technology is ever changing its essential that we document the decisions we make or we can loose those reasoning over time, or in bigger projects end up jumping from meeting to meeting essentially discussing the same thing. This is a cost overhead in time and is a risk in terms of miscommunication or the possibility that things get lost.  Its possible to have meetings discuss requirements and keep things together within meeting minutes but architects should be looking to understand these things consistently and to group information together, in a way that in a years time when we look at answering the question “why did we buy this, and can we replace it?” we have something we can go back to.

Please feel free to comment ­čÖé

User Stories

Introducing User Stories, an easy mechanism to capture stakeholder needs and requirements.

The Basics of User Stories

There are many forms a user story can take but I introduce a simple one here in the video below.

To sum it up quickly

As <someone> I want to <do something> in order to <achieve value>

Its an easy mechanism we can use to focus users into creating a basic form of requirement.

A practical example

Lets take a look at some basic examples.

  • As a customer CxO I want to outsource my website management in order to reduce risk of unexpected maintenance costs
  • As a customer CxO I want to outsource my website management in order to reduce operational costs
  • As a customer end user I want to have an uninterrupted service experience in order to reduce wasted time
  • As the web service product manager I want to have efficient operations in order to maintain a 30% margin
  • As the web service product manager I want to have a completely automated deployment of my core services in order to be scalable
  • As the web service product manager I want to have a completely automated deployment of my core services in order to reduce the chance of manual error
  • As the web service product manager I want to have a completely automated deployment of my core services in order to have fast deployment times

Above are some typical examples that might come up in a planning session with product management. I could easily go to my stakeholders in separate meetings, and work with them to build a more complete list.

Turning this into ArchiMate

Is fairly easy. Again I showed it in the video but I will demonstrate. I don’t normally insist architects create a view like the one below but it has advantages if you are trying to extract value. Take a look.

I’ve done this quickly. Note I slightly changed the wording for both values and requirements – this is because we have to remember they are elements in a model. This means they need to be able to stand as independently and tell a story by themselves.

Viewing them this way means makes it easier to see which requirements yield the most value, and makes it easier for us to tie things together. We could use these user stories as a motivation view in our work planning.

You can of course also use this very basic motivation view as the basis for a requirements realization.

You could also use the work to group together values.

I will be talking a lot more about requirements of different kinds and approaches to them. Its a big subject – needless to say, User stories offer an easy way to get started capturing the needs of stakeholders.