SAIP (Chapter 9): Documenting Software Architectures
This chapter reemphasizes the importance of documenting software architecture and prescribes possible templates and approaches to documenting an architecture. The authors place the audience/stakeholders as the most important target for putting together an architectural document and suggests UML as the most popular notation for represting architectural elements in the document.
I agree with the authors' suggested cookbook for writing an architectural document, particularly for not restricting the architecture to a said number of views as we witness in the 4+1 model of architecture. The author also gives examples of views that could be considered and provides us with ways of tying these views together. Views are developed based on the mix of stakeholders and the becomes an essential tool for communicating amongst the various stakeholders. The use of view catalogs and templates to ease navigation and validation of the architecture is great and, in my opinion, should be adapted in all documentation.
In my experience, architectural documents could be the most cumbersome and time-consuming documents to put together. Especially since most of it is put together before the project is tangible. Most of it is highly abstract and evolves with the project. In projects where time constraints are tight, it becomes increasingly difficult to keep the document in sync with the project architecture. And particularly in cases where the specified architecture fails feasibility tests, due to erroneous requirements or lack of resources etc, it becomes very difficult for the architect to leave real development behind and focus on correcting several pages of invalid documentation. Therefore, I embrace the idea of having teams document the various structures they work on, using an organization standard, and possibly having the architect tie the pieces together. That way, each team is responsible to keeping the documents in sync with the project, while allowing junior developers to gain a knack for documenting architectures and a better sense of understanding other people's architectures.
I agree with the authors' suggested cookbook for writing an architectural document, particularly for not restricting the architecture to a said number of views as we witness in the 4+1 model of architecture. The author also gives examples of views that could be considered and provides us with ways of tying these views together. Views are developed based on the mix of stakeholders and the becomes an essential tool for communicating amongst the various stakeholders. The use of view catalogs and templates to ease navigation and validation of the architecture is great and, in my opinion, should be adapted in all documentation.
In my experience, architectural documents could be the most cumbersome and time-consuming documents to put together. Especially since most of it is put together before the project is tangible. Most of it is highly abstract and evolves with the project. In projects where time constraints are tight, it becomes increasingly difficult to keep the document in sync with the project architecture. And particularly in cases where the specified architecture fails feasibility tests, due to erroneous requirements or lack of resources etc, it becomes very difficult for the architect to leave real development behind and focus on correcting several pages of invalid documentation. Therefore, I embrace the idea of having teams document the various structures they work on, using an organization standard, and possibly having the architect tie the pieces together. That way, each team is responsible to keeping the documents in sync with the project, while allowing junior developers to gain a knack for documenting architectures and a better sense of understanding other people's architectures.
posted by Toniez alamo de la mite at
6:45 PM
0 Comments:
Post a Comment
<< Home