Mumbai University > Information Technology > Semester 7 > Software Architecture.

• The architecture for a system depends on the requirements levied on it so the documentation should be sufficiently abstract to be quickly understood by new employees but sufficiently detailed to serve as a blueprint for analysis. The architectural documentation may be different for different domain; for example security analysis may well be different from the architectural documentation.
• Architecture documentation is both prescriptive and descriptive. That is, for some audiences it prescribes what should be true by placing constraints on decisions to be made. For other audiences it describes what is true by recounting decisions already made about a system's design.
• All of this depicts that different stakeholders for the documentation have different needs, different kinds of information, different levels of information, and different treatments of information. We should not expect to produce one architectural document and have every consumer read it in the same way.
• One of the most fundamental rules for architecture documentation in particular, is to write from the point of view of the reader. Documentation that was easy to write but is not easy to read will not be useful.
• Understanding who the stakeholders are and how they will want to use the documentation will help organize it and make it more usable for them.
• In addition, each stakeholders come in two varieties: seasoned and new. A new stakeholder will want information similar in content to what his seasoned counterpart wants, but in smaller and more introductory doses. Architecture documentation is a key means for educating people who need an overview: new developers, funding sponsors, visitors to the project, etc.
• New architects are interested in learning how their predecessors tackled the difficult issues of the system and why particular decisions were made.