Architectural documentation: Views makes things clear

When Architects are involved in the definition of architecture, it is also their responsibility to represent it in such a way that all the audience understands it very well. This is more important when architects are involved in selling the proposed architecture of a solution as part of pre-sales process. They have to present concrete justification points to the potential customers to make them understand why their proposed solution architecture is best. When the solution presentation happens, it may involve various high level stakeholders from business, IT, technology etc. Same is the case when IT of an enterprise is pitching for an imitative or a new project; unless business is convinced, IT will not get a “go” signal and budget allocation.

The target audience of architecture can be categorized into two:

1. High level stakeholders like CIO, CEO, CFO, EA etc from business & IT who influence decisions significantly
2. Medium / Low level stakeholders like Tech. leads, developers who will actually help in realization of the architecture. It may also include other fellow architects from various technology domains like security, performance.

Unless the Architect who is responsible for an application’s architecture is able to document the architecture in such a way that it is clear for the above categorized audience, it will not move anywhere. Depending upon the target audience, architecture needs to be documented either only with the high level details or accurately in a very detailed manner. High level stakeholders (as classified above) many not be interested in the details of the architecture related to its implementation whereas developers & tech. leads will be very much interested in it. So, based on the target audience, it is the duty of the architect to use appropriate views & models.

There are various models & views used by the industry to help the architects in effectively documenting the architecture. Generally adopted views / viewpoints are Conceptual view, logical view, technical view & physical view. There are no industry wide naming standards or taxonomy related to documenting architecture. Some enterprises use the names like logical architecture, deployment architecture, conceptual architecture, etc to document architecture. Some even use business architecture, functional architecture (!) without knowing what content to put under such headings. Point here is that irrespective of views / naming standards that is used, architect should be aware the target audience & their expectations before planning for architectural documentation. Unless an architecture is flavor with various appropriate views / viewpoints in its documentation, it will not be clearly understandable by its audience. It’s like some blind men touching a hug banyan tree and making their own impressions about it.

In addition to 4 + 1 view as recommended by rational (which is in general followed by practicing architects), architects should use additional views / viewpoints based on the target audience. For example, it an architect is defining architecture for a complex system where security is considered as highly important quality, than that project may have a dedicated security architect. May be even in that case, there could be a demand from business & IT to get the architecture evaluated by security domain experts. In that case, architect should use Security view, in addition to other standard views.
Point here is that architect of architecture should use appropriate views / viewpoints / models for documenting architecture so that the target audience gets more clear understanding of the architecture from their domain perspective. If not, it will lead to more ambiguity & mis-interpretation and more room for conflicts.