The Check List for Documenting Software Architecture.

                       Software architecture has emerged as an important sub-discipline of software engineering,particularly in the realm of large system development. While there is no universal definition of software architecture, there is no shortage of them.

However What those definitions have in common is their emphasis on architecture as a description of a system as a sum of smaller parts, and how those parts relate to and cooperate with each other to perform the work of the system. Architecture gives us intellectual control over the very complex by allowing us to substitute the complex with a set of interacting pieces, each one of which is substantially simpler than the whole.

Why we need Software Architecture in a document ?

Professor Dijk-stra’s consideration for the reader reflects his classic manners, but it also gives us a new and useful concept of the effort associated with a document. Usually we just count how long it takes to write. Dijkstra taught us to be concerned with how long it takes to use.

• The goal of documenting an architecture is to write it down so that others can successfully use it, maintain it, and build a system from it. The blue-print for developing a Software System.

• Documentation exists to further architecture’s uses as a means of education, as a vehicle for communication among stakeholders, and as the basis for analysis.

• Documenting an architecture is a matter of documenting the relevant views and then adding documentation that applies to more than one view.

• Documentation should pay for itself by making development activities less costly.

Check List( 7 Rules)  for documenting the Software Architecture.

1.  Write documentation from the Reader's point of view.

• Find out who your readers are, what they know, and what they expect from the  document. The best way to get to know your stakeholder is to have a informal chat and make sure not doing any wrong assumptions on them.

• Don't write the content as  it easy for you or as it come to your mind, make sure you get the big picture of the overall document. You can break down the document into the sections and make sure relevant sections provide answers to some of architectural concerns.

• Avoid specialized terms and jargon, since reader may not be sharing same terms as you do, so add a glossary to define your terms.

• Avoid overuse of acronyms , if your phrase is not used many times in the doc or short in length then better to use as it is.

2. Avoid Unnecessary repetition.

• Need to make sure same content is not repeated on different places , which will put reader into trouble when when you had updated the content in one place and forgot to change at all other places. So the best way to handle this, keep common content referenced by a reference number  or using hyper link ( in a soft copy ).

3. Avoid Ambiguity

Ambiguity occurs when documentation can be interpreted in more than one way and at least one of those ways is incorrect.

• Avoid needless repetition ( as in rule 2 above ) 

• Use well defined notations and precise semantics as much as possible.

• The ubiquitous box-and-line diagrams that people always draw on whiteboards are one of the greatest sources of ambiguity in architecture documentation , if you use such make sure you have notation to explain what it means for. Simple arrow can represent many things like, calling the other module , data flow  etc.

4. Use standard Organisation/Template.

• It helps the reader navigate the document and find specific information quickly

• The template already provides an outline of the important topics to cover and  helps the document writer plan and organize the contents.

• It reveals what work remains to be done by the number of sections labeled “TBD”

5. Record rationale

• You should record why you made them the way you did. You should also record the important or most likely alternatives you rejected and state why
• You will find yourself revisiting the same arguments and wondering why you didn’t take another path.

6. Keep Documentation Current but Not too Current.

• Documentation that is somehow inadequate to answer the current question needs to be fixed.
• Updating it and then referring the questioner to it will deliver a strong message that the documentation is the final, authoritative source for information.
• No need to keep updating the document on every decision made instantly, rather give it a proper time to go through final review /approval and then add it as the final update to the document.

7. Review Documentation for the Fitness of  purpose.

• Before a document is released, have it reviewed by representatives of the community or communities for which it was written.Only the intended users of a document will be able to tell you whether it contains the right information.