Saturday, December 27, 2008

Software Architecture Documentation.Part-I

In my current project I’ve been assigned the task to make a nice-and-easy-to-understand software architecture document. The system which we are developing is brand new one and it connects 95% of the products available in our bank. As a follower of agile methodology, we need to be very precise with our document. Unlike waterfall model, we did not want to over blot by High Level Design (HLD), Low Level design (LLD) documents. Business Requirement Documents (BRD) by the Business Analyst (BA) is the source of our document. So, the scope of the document was to replace 100 pages of FS by some concise but meaningful document. As a matter of fact, UML is the language of choice for our document, because its n-dimensional   graphical representation explains the scope of the proposed system with details workflow and business processes. Also, all parties involved in the project, viz. Business, BA, Developer, Architect, Manager can participate to make it robust and powerful. From the development team I get the chance to work with Use cases and activity diagrams and it is very interesting job with a bit of pain. But as they say “No pain, No gain”, I welcome this pain to have a wonderful experience.
As we know architecture is the blue print of a proposed system, either for software or construction or any other industry. So, documenting the architecture is a very crucial task. Multiple parties involved in the project have different expectations from the document. Business people don’t care about the jargons of UML. They just want to click on the screen and get the business logic to be executed in the expected manner as agreed in BRD.BA wants to make sure that the activity diagrams rightly explain the workflow, so on and so forth. Based on his previous experience my boss advised me to focus on the below UML diagrams:- 
  • Context of the Project. It specifies what the proposed system is supposed to do. How is going make the difference with the existing process
  • Domain Model. It is the repository of all vocabularies used in the project. If any new jargon is discovered, this model needs to be updated as well.
  • Data Model. It is basically the various database tables and/or external downloads from other system.
  • Business Process. An array of activities which is system driven and user don’t participate with it explicitly. For example, we need to load all the trades and bonds before the user start clicking on the system. An loading the trades and bonds consists of several steps which we call business process
  • Use cases. It is explicitly user driven activity. For example, users added a new product in the system or send a e-mail to some customer, that is an use case. I’ll explain it more details in the later part of this post
  • So on and so forth
What is a use case? After asking google, I got millions of records within a fraction of second. But more I dig into the links, the more I get diverted from my objective. It’s seems to be like modern art, which can be explained from different angles. For some people, it may be just a few lines of scratches on a paper, but could be an interesting fact. Anyway, wikipedia [] defined it with proper attributes and let me share what I understood.
A use case is a collection of activities which will be performed on the proposed application. It must be explained with goals, summary, pre-conditions, post-conditions, exception handlings, notes, issues (if anything is note clear from BA/ Business side), so on and so forth. It should be assisted with activity diagram(s) to explain how the use case will be initiated and the state of the system will be modified after the use case is performed. For example currency code maintenance can be thought as a use case which will do a typical CRUD (Create, Read, Update and Delete) operation. ISO currency code is basic entity in bank, so maintenance of it is very common. Initially I made four different use cases for each CRUD operations. But that was not a practical and reasonable approach. A use case can be compared as a Java class which contains variables, object references, methods, constructors etc. If you just think of variable, it is just an attribute which is useless unless it is associated with a class or interface. Same is true for a use case. It is not just an UML diagram which explains the click event by the user on the screen, but an entire process to describe how the system will behave after an action is taken by the user and we need to capture the behaviour of the system from all possible angles. That makes a use case. So, if we describe the CRUD operation on currency code with all possible attributes, I think we can create a use case. But, there might be some room for more improvement and only experience and teach us how to do it.