Following my previous blog on Working With Projects & Dependencies I wanted to say a little on working with deliverable’s and avoiding some pitfalls.
I wrote this blog to address some trends I am now seeing with new architects modelling implementation and migration architecture for the first time because its really important to get this right. This is aimed at beginners.
What is a deliverable?
The ArchiMate 3.1 Specification says.
A deliverable represents a precisely-defined result of a work package.
So simply put, when we do work in a work package, we expect a result. Work packages realize deliverables & in my last blog I showed how I manage link dependencies from one work package to another by accessing (reading) the deliverable that is realized by another project.
Its not the only way we can work with this, but its a way that works.
Common Issues In Naming Deliverables
Correctly Scoping The Name
Each element in an architecture model is reusable and may be used in many views. This means you need to be specific to the context you are modelling in. For example lets say we name our deliverable “High Level Design Documentation”. It is a fairly generic name that would be an object that many architects may want to use. When we are thinking of using specific elements in specific contexts we need to get this level of abstraction right. If we are documenting an element named “High Level Design Documentation” then we can only document things that are specific to all high level designs (HLDs). if we needed to say something specific about a project, we would need to name it in a way that’s identifiable as a project specific element; Its far better to name it “Project A – High Level Design Documentation” in such a case.
I spoke about this in my blog Documenting An Architecture Model.
How we scope the element is dependent on how we will use it. In the case of “High Level Design Documentation” – If every project has exactly the same requirement to deliver exactly the same type of document its tempting to just reuse the same element on each project. That’s a really bad thing if you are trying to dependency Map because then every work package would have a relationship to the same element and you would have no way of differentiating between the different deliverables. Figure 2 is an example:
The view looks easily understandable but it is bad in the when we look at this in the model. In figure 3 we can see the relationships for the High Level Design Documentation Element. There’s no way of telling that project A can run completely independent of project C, because project C accesses high level design documentation, and there is no difference between the element realized by project A to the one realized by project B or C.
Correctly Scoping the Element With Specialization
So if we want to show we have a standard high level design and maybe have the documentation of that element reflect the standard, what do we do? The solution to this problem is simple. we use a specialization.
Figure 4 shows several deliverable’s being a specialization of a standard deliverable.
Confusing Deliverables With Requirements Or Goals
I have seen sometimes people define deliverable like requirements – where people are thinking about what a project needs to do, rather than what a project needs to deliver. You can think of a set of defined deliverable as a checklist of things that a project should produce. In general I don’t go crazy with this idea. If you saw my blog on High Level Design you could see a design can be composed from many documents, and If I did decide a HLD was a deliverable I wouldn’t model each document, unless I have a very special reason to do so.
In fact if a high level design is part of our standard project documentation – I may not model them specifically at all (See Just Enough Architecture). Some examples of deliverables:
- Project Standard Documentation
- Fully Configured Production environment for Project X
- Updated InfoSec Policy
- A Deployment Process
- ISO27k Audit Policy Pass
Looking at the deliverable above you can see a deliverable can be almost anything. I nearly didn’t include ISO27k Audit Policy Pass. The reason being that although it may be a deliverable, its easy to confuse it with a requirement. Deliverable’s are effectively an outcome of the work done to realize a requirement, or goal.
In the documentation for the elements above I might specify further what we need to achieve that deliverable. For example I might elaborate on “Fully Configured Production Environment For Project X” by saying something like:
Production environment implemented and documentation of its acceptance provided by operations and the all the stakeholders shown in the view “Project X Stakeholders”
We don’t need to write a book, but we do need to be precise; specific and measurable.
Focusing On Delivering Documentation
Ok, there are times when documentation is key to the progression of other projects and dependencies, and documentation can definitely be a deliverable. Don’t get lost in doing architecture there – our goal at the end of the day is to have projects deliver value, not to only document. One of my own managers favorite sayings is “Build the hospital, don’t only design it”. The message being is we can spend a long time trying to design a perfect thing, but unless we have a practical implementation for it, its useless. For that reason when looking at any implementation and migration architecture in my own company, we always look to see if there is a deliverable that goes beyond documentation. I think this is good general advice, but I mention this especially for my own architects…
Modelling Too Many Things At The Top Level
In figure 4 we showed Standard high Level Design Documentation as a common deliverable. Standard high level designs may be composed of several documents, and unless there is a very specific need we do not want to model project specific instances of all of them. It would be better to create a view showing the composition of a high level design like in figure 5.
Summing this Up
This blog was really targeted to address some issues I am seeing right now from some people that are new to modelling completely, and I may have repeated things that I have said in other blogs, but I hope other people find this useful. Having a well defined set of deliverables really helps set expectations.