Recently a conversation came up on the Illegal Arguement converasation about ‘how much architecture is needed’, and I responded in a post on their mailing list. This blog entry is an elaboration on that post.
In my opinion, that depends on your organisational context.
Some of the Architecture documentation I’ve constructed in my professional life has been in the kind of environment which is all about butt covering and decision justification, sadly the communication of concepts to a team of developers is of secondary concern.
In some cases, an external party would be included to do an Architecture Review on a design prior to approval. Generally this was motivated by a visible failure in the past and there was a political concern that needed to be mitigated. In short, it was an expensive form of box ticking.
As an outcome, the reviewed documents needed to be detailed and contain lots of redundant information and statements of what most would believe was the blatently obvious. Further more, they needed to be structured around an industry best practise. Not because it was the necessary thing, but because it was the expected thing.
By their nature these kind of documents were also completed well ahead of software construction, usually at business case stage and with technologies and frameworks picked like you might select a breakfast cereal (From
reading ‘the back of the box’). A depressing way of doing things, but unavoidable given time and circumstance.
So whats the answer?
Personally, I feel its all proportional to how much contact you have with the implementers of the solution and the strength of that relationship. In the environment I’m referring to above, I was distant from them, in fact, on some of the projects, I wasn’t involved in delivery at all. Just the intial documents and pre-project meetings.
If thats your situation then there is no substitute for detail. You needed to be explicit and obvious as the contractor who turned up yesterday is likely going implement the project ‘their way’ and it seems, people can come up with no end of variation from what rational thought might expect.
Further more if you are in a hostile environment, full of politics and a low acceptance for any perceived failure (i.e. an ‘Enterprise’) then you are in for a hard time and you better get used to TOGAF, Zachmann, UML and your favorite design patterns book.
But, if you are directly involved in the delivery and a good relationship with the implementors, then I believe the required documentation should be ‘not much’, you might even suffice maybe a list of bullet points and a few high level diagrams and suppliment it a constant stream of guiding conversations during the delivery process.
)