One of the major challenge I felt as an architect is that client or project stakeholders want everything to be put in the architectural documents. A couple of days ago, I was in the conference with the client’s Project Manager. We were discussing the architecture of the new application, we are going to develop. I have mentioned major classes and components in the rational rose model. But the Project Manager was insisting that I should mention every class in the model. And as this was not enough, he said that I should not miss any property or method of any class, public or private. And to make the things worst, requirements were not finalized at that time. We were expecting next version of the requirement documents in a couple of days. I had a hard time to convince PM that it’s neither possible not feasible to put so much details in the documents. So, I decided to post my thoughts on this matter.
What should be the depth of architecture?
This is the most challenging question for an architect. At the top level you can decide. For example you can settle down that the use case diagrams, component diagrams, class diagrams and sequential diagrams will do the work for your application. However, the problems comes when you decide depth of these diagrams. I have seen use case diagrams defined from the 30,000 feet to 100 feet.
For example, while looking at the design document for a web project, I found only one use case. This has two actors – webmaster and visitor. And there was only one use case – the application itself. A good example of 30,000 feet altitude view 
.
Anther extreme case was with a windows application with only three forms. And they have defined around 40 use cases for this. Each method was a use case in itself. A good example of 100 feet (or even 10 feet) altitude.
There are many same stories for other diagrams as well. As I stated in the beginning of this post, defining each and every method of each class in a big application is 10 feet altitude. This is neither feasible nor practical. I feel that we should remain at an altitude of 1000 feet to 5000 feet. At this range, we provide the details which are small enough for the management to have a bird’s eye view of the architecture and good enough for the development team to have guidelines to code. This does not bound the developers to the defined architecture – they are free (to certain extent) to showcase their creativity. Having clear understanding of the objectives of the architectural documents makes the decision making easier.
What is the objective of architecture and design document?
There are two types of technical documents – informational and manual. Manuals are supposed to have detailed information about any product, service, or whatever. But informational documents are meant for communication. If you put too much details in an informational document, its will be a waste of efforts. No one is going to read it line by line. Communication should be short and to-the-point. According to easycommunication.info, communication should be “adequate briefing of the recipient”. Notice that they use the word briefing. The same is true for architectural document.
These documents are supposed to communicate main architectural decisions and relationship with major components of the system. They should include only relevant information. If you put all the details in the architectural documentation, it will become a manual of the system and will fail to communicate its core purpose. So, what should be included in the architecture and design documents? This post is getting longer, so I will answer this question in the words of Martin Fowler, the architecture guru.
Do we define everything in the architecture?
Martin Fowler says “Draw a class diagram that shows the important classes in the package but not necessarily all of them”. He further tells that “For each class show only the key attributes and operations, definitely don’t show all of them”.
More of this stuff in the next post. I know you are getting bored.
